Package babel :: Module numbers |

# Module numbers

Locale dependent formatting and parsing of numeric data.

The default locale for the functions in this module is determined by the following environment variables, in that order:

> - `LC_NUMERIC`,
> - `LC_ALL`, and
> - `LANG`

Classes
| NumberFormatError Exception raised when a string cannot be parsed into a number.

Functions
`unicode` |
format_number(number, locale=None) Return the given number formatted for a specific locale. |
`unicode` |
format_decimal(number, format=None, locale=None) Return the given decimal number formatted for a specific locale. |
`unicode` |
format_currency(number, currency, format=None, locale=None) Return formatted currency value. |
`unicode` |
format_percent(number, format=None, locale=None) Return formatted percent value for a specific locale. |
`unicode` |
format_scientific(number, format=None, locale=None) Return value formatted in scientific notation for a specific locale. |
`long` |
parse_number(string, locale=None) Parse localized number string into a long integer. |
`float` |
parse_decimal(string, locale=None) Parse localized decimal string into a float. |

Function Details

### format_number(number, locale=None) |
Return the given number formatted for a specific locale.
    >>> format_number(1099, locale='en_US')
    u'1,099'
Parameters: `number` - the number to format `locale` - the Locale object or locale identifier Returns: `unicode` the formatted number

### format_decimal(number, format=None, locale=None) |
Return the given decimal number formatted for a specific locale.
    >>> format_decimal(1.2345, locale='en_US')
    u'1.234'
    >>> format_decimal(1.2346, locale='en_US')
    u'1.235'
    >>> format_decimal(-1.2346, locale='en_US')
    u'-1.235'
    >>> format_decimal(1.2345, locale='sv_SE')
    u'1,234'
    >>> format_decimal(12345, locale='de')
    u'12.345'
The appropriate thousands grouping and the decimal separator are used for each locale:
    >>> format_decimal(12345.5, locale='en_US')
    u'12,345.5'
Parameters: `number` - the number to format `format` `locale` - the Locale object or locale identifier Returns: `unicode` the formatted decimal number

### format_currency(number, currency, format=None, locale=None) |
Return formatted currency value.
    >>> format_currency(1099.98, 'USD', locale='en_US')
    u'$1,099.98'
    >>> format_currency(1099.98, 'USD', locale='es_CO')
    u'US$\xa01.099,98'
    >>> format_currency(1099.98, 'EUR', locale='de_DE')
    u'1.099,98\xa0\u20ac'
The pattern can also be specified explicitly:
    >>> format_currency(1099.98, 'EUR', u'¤¤ #,##0.00', locale='en_US')
    u'EUR 1,099.98'
Parameters: `number` - the number to format `currency` - the currency code `locale` - the Locale object or locale identifier Returns: `unicode` the formatted currency value

### format_percent(number, format=None, locale=None) |
Return formatted percent value for a specific locale.
    >>> format_percent(0.34, locale='en_US')
    u'34%'
    >>> format_percent(25.1234, locale='en_US')
    u'2,512%'
    >>> format_percent(25.1234, locale='sv_SE')
    u'2\xa0512\xa0%'
The format pattern can also be specified explicitly:
    >>> format_percent(25.1234, u'#,##0\u2030', locale='en_US')
    u'25,123\u2030'
Parameters: `number` - the percent number to format `format` `locale` - the Locale object or locale identifier Returns: `unicode` the formatted percent number

### format_scientific(number, format=None, locale=None) |
Return value formatted in scientific notation for a specific locale.
    >>> format_scientific(10000, locale='en_US')
    u'1E4'
The format pattern can also be specified explicitly:
    >>> format_scientific(1234567, u'##0E00', locale='en_US')
    u'1.23E06'
Parameters: `number` - the number to format `format` `locale` - the Locale object or locale identifier Returns: `unicode` value formatted in scientific notation.

### parse_number(string, locale=None) |
Parse localized number string into a long integer.
    >>> parse_number('1,099', locale='en_US')
    1099L
    >>> parse_number('1.099', locale='de_DE')
    1099L
When the given string cannot be parsed, an exception is raised:
    >>> parse_number('1.099,98', locale='de')
    Traceback (most recent call last):
        ...
    NumberFormatError: '1.099,98' is not a valid number
Parameters: `string` - the string to parse `locale` - the Locale object or locale identifier Returns: `long` the parsed number Raises: `NumberFormatError` - if the string can not be converted to a number

### parse_decimal(string, locale=None) |
Parse localized decimal string into a float.
    >>> parse_decimal('1,099.98', locale='en_US')
    1099.98
    >>> parse_decimal('1.099,98', locale='de')
    1099.98
When the given string cannot be parsed, an exception is raised:
    >>> parse_decimal('2,109,998', locale='de')
    Traceback (most recent call last):
        ...
    NumberFormatError: '2,109,998' is not a valid decimal number
Parameters: `string` - the string to parse `locale` - the Locale object or locale identifier Returns: `float` the parsed decimal number Raises: `NumberFormatError` - if the string can not be converted to a decimal number