Mercurial > babel > mirror
diff doc/numbers.txt @ 124:98dcabc99308 trunk
Split docs on date and number formatting.
author | cmlenz |
---|---|
date | Mon, 18 Jun 2007 15:15:31 +0000 |
parents | |
children | f9f6f740b595 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/numbers.txt @@ -0,0 +1,111 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +========================== +Number Formatting +========================== + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +Support for locale-specific formatting and parsing of numbers is provided by +the ``babel.numbers`` module: + +.. code-block:: pycon + + >>> from babel.numbers import format_number, format_decimal, format_percent + +Examples: + +.. code-block:: pycon + + >>> format_decimal(1.2345, locale='en_US') + u'1.234' + >>> format_decimal(1.2345, locale='sv_SE') + u'1,234' + >>> format_decimal(12345, locale='de_DE') + u'12.345' + + +Pattern Syntax +============== + +While Babel makes it simple to use the appropriate number format for a given +locale, you can also force it to use custom patterns. As with date/time +formatting patterns, the patterns Babel supports for number formatting are +based on the `Locale Data Markup Language specification`_ (LDML). + +Examples: + +.. code-block:: pycon + + >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en') + u'-1.23' + >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en') + u'(1.23)' + +The syntax for custom number format patterns is described in detail in the +the specification. The following table is just a relatively brief overview. + + .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Number_Format_Patterns + + +----------+-----------------------------------------------------------------+ + | Symbol | Description | + +==========+=================================================================+ + | ``0`` | Digit | + +----------+-----------------------------------------------------------------+ + | ``1-9`` | '1' through '9' indicate rounding. | + +----------+-----------------------------------------------------------------+ + | ``@`` | Significant digit | + +----------+-----------------------------------------------------------------+ + | ``#`` | Digit, zero shows as absent | + +----------+-----------------------------------------------------------------+ + | ``.`` | Decimal separator or monetary decimal separator | + +----------+-----------------------------------------------------------------+ + | ``-`` | Minus sign | + +----------+-----------------------------------------------------------------+ + | ``,`` | Grouping separator | + +----------+-----------------------------------------------------------------+ + | ``E`` | Separates mantissa and exponent in scientific notation | + +----------+-----------------------------------------------------------------+ + | ``+`` | Prefix positive exponents with localized plus sign | + +----------+-----------------------------------------------------------------+ + | ``;`` | Separates positive and negative subpatterns | + +----------+-----------------------------------------------------------------+ + | ``%`` | Multiply by 100 and show as percentage | + +----------+-----------------------------------------------------------------+ + | ``‰`` | Multiply by 1000 and show as per mille | + +----------+-----------------------------------------------------------------+ + | ``¤`` | Currency sign, replaced by currency symbol. If doubled, | + | | replaced by international currency symbol. If tripled, uses the | + | | long form of the decimal symbol. | + +----------+-----------------------------------------------------------------+ + | ``'`` | Used to quote special characters in a prefix or suffix | + +----------+-----------------------------------------------------------------+ + | ``*`` | Pad escape, precedes pad character | + +----------+-----------------------------------------------------------------+ + + +Parsing Numbers +=============== + +Babel can also parse numeric data in a locale-sensitive manner: + +.. code-block:: pycon + + >>> from babel.numbers import parse_decimal, parse_number + +Examples: + +.. code-block:: pycon + + >>> parse_decimal('1,099.98', locale='en_US') + 1099.98 + >>> parse_decimal('1.099,98', locale='de') + 1099.98 + >>> parse_decimal('2,109,998', locale='de') + Traceback (most recent call last): + ... + NumberFormatError: '2,109,998' is not a valid decimal number