numbers.txt 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113
  1. .. -*- mode: rst; encoding: utf-8 -*-
  2. ==========================
  3. Number Formatting
  4. ==========================
  5. .. contents:: Contents
  6. :depth: 2
  7. .. sectnum::
  8. Support for locale-specific formatting and parsing of numbers is provided by
  9. the ``babel.numbers`` module:
  10. .. code-block:: pycon
  11. >>> from babel.numbers import format_number, format_decimal, format_percent
  12. Examples:
  13. .. code-block:: pycon
  14. >>> format_decimal(1.2345, locale='en_US')
  15. u'1.234'
  16. >>> format_decimal(1.2345, locale='sv_SE')
  17. u'1,234'
  18. >>> format_decimal(12345, locale='de_DE')
  19. u'12.345'
  20. Pattern Syntax
  21. ==============
  22. While Babel makes it simple to use the appropriate number format for a given
  23. locale, you can also force it to use custom patterns. As with date/time
  24. formatting patterns, the patterns Babel supports for number formatting are
  25. based on the `Locale Data Markup Language specification`_ (LDML).
  26. Examples:
  27. .. code-block:: pycon
  28. >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en')
  29. u'-1.23'
  30. >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en')
  31. u'(1.23)'
  32. The syntax for custom number format patterns is described in detail in the
  33. the specification. The following table is just a relatively brief overview.
  34. .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Number_Format_Patterns
  35. +----------+-----------------------------------------------------------------+
  36. | Symbol | Description |
  37. +==========+=================================================================+
  38. | ``0`` | Digit |
  39. +----------+-----------------------------------------------------------------+
  40. | ``1-9`` | '1' through '9' indicate rounding. |
  41. +----------+-----------------------------------------------------------------+
  42. | ``@`` | Significant digit |
  43. +----------+-----------------------------------------------------------------+
  44. | ``#`` | Digit, zero shows as absent |
  45. +----------+-----------------------------------------------------------------+
  46. | ``.`` | Decimal separator or monetary decimal separator |
  47. +----------+-----------------------------------------------------------------+
  48. | ``-`` | Minus sign |
  49. +----------+-----------------------------------------------------------------+
  50. | ``,`` | Grouping separator |
  51. +----------+-----------------------------------------------------------------+
  52. | ``E`` | Separates mantissa and exponent in scientific notation |
  53. +----------+-----------------------------------------------------------------+
  54. | ``+`` | Prefix positive exponents with localized plus sign |
  55. +----------+-----------------------------------------------------------------+
  56. | ``;`` | Separates positive and negative subpatterns |
  57. +----------+-----------------------------------------------------------------+
  58. | ``%`` | Multiply by 100 and show as percentage |
  59. +----------+-----------------------------------------------------------------+
  60. | ``‰`` | Multiply by 1000 and show as per mille |
  61. +----------+-----------------------------------------------------------------+
  62. | ``¤`` | Currency sign, replaced by currency symbol. If doubled, |
  63. | | replaced by international currency symbol. If tripled, uses the |
  64. | | long form of the decimal symbol. |
  65. +----------+-----------------------------------------------------------------+
  66. | ``'`` | Used to quote special characters in a prefix or suffix |
  67. +----------+-----------------------------------------------------------------+
  68. | ``*`` | Pad escape, precedes pad character |
  69. +----------+-----------------------------------------------------------------+
  70. Parsing Numbers
  71. ===============
  72. Babel can also parse numeric data in a locale-sensitive manner:
  73. .. code-block:: pycon
  74. >>> from babel.numbers import parse_decimal, parse_number
  75. Examples:
  76. .. code-block:: pycon
  77. >>> parse_decimal('1,099.98', locale='en_US')
  78. 1099.98
  79. >>> parse_decimal('1.099,98', locale='de')
  80. 1099.98
  81. >>> parse_decimal('2,109,998', locale='de')
  82. Traceback (most recent call last):
  83. ...
  84. NumberFormatError: '2,109,998' is not a valid decimal number
  85. .. note:: Number parsing is not properly implemented yet