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