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=`'``nl_NL``'`) Return the given number formatted for a specific locale. |

`unicode`

format_decimal(number, format=None, locale=`'``nl_NL``'`) Return the given decimal number formatted for a specific locale. |

`unicode`

format_currency(number, currency, format=None, locale=`'``nl_NL``'`) Return formatted currency value. |

`unicode`

format_percent(number, format=None, locale=`'``nl_NL``'`) Return formatted percent value for a specific locale. |

`unicode`

format_scientific(number, format=None, locale=`'``nl_NL``'`) Return value formatted in scientific notation for a specific locale. |

`long`

parse_number(string, locale=`'``nl_NL``'`) Parse localized number string into a long integer. |

`float`

parse_decimal(string, locale=`'``nl_NL``'`) Parse localized decimal string into a float. |

Function Details

### format_number(number, locale=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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=`'``nl_NL``'`)

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