Mercurial > babel > mirror

annotate doc/numbers.txt @ 609:01a75fec90f0 stable-0.9.x tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge r661 from trunk into 0.9 maintenance branch
author fschwarz
date Mon, 15 Oct 2012 20:04:21 +0000
parents f9f6f740b595
children
rev   line source
124
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
2
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
3 ==========================
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
4 Number Formatting
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
5 ==========================
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
6
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
7
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
8 .. contents:: Contents
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
9 :depth: 2
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
10 .. sectnum::
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
11
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
12
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
13 Support for locale-specific formatting and parsing of numbers is provided by
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
14 the ``babel.numbers`` module:
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
15
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
16 .. code-block:: pycon
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
17
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
18 >>> from babel.numbers import format_number, format_decimal, format_percent
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
19
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
20 Examples:
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
21
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
22 .. code-block:: pycon
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
23
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
24 >>> format_decimal(1.2345, locale='en_US')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
25 u'1.234'
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
26 >>> format_decimal(1.2345, locale='sv_SE')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
27 u'1,234'
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
28 >>> format_decimal(12345, locale='de_DE')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
29 u'12.345'
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
30
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
31
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
32 Pattern Syntax
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
33 ==============
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
34
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
35 While Babel makes it simple to use the appropriate number format for a given
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
36 locale, you can also force it to use custom patterns. As with date/time
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
37 formatting patterns, the patterns Babel supports for number formatting are
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
38 based on the `Locale Data Markup Language specification`_ (LDML).
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
39
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
40 Examples:
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
41
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
42 .. code-block:: pycon
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
43
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
44 >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
45 u'-1.23'
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
46 >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
47 u'(1.23)'
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
48
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
49 The syntax for custom number format patterns is described in detail in the
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
50 the specification. The following table is just a relatively brief overview.
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
51
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
52 .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Number_Format_Patterns
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
53
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
54 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
55 | Symbol | Description |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
56 +==========+=================================================================+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
57 | ``0`` | Digit |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
58 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
59 | ``1-9`` | '1' through '9' indicate rounding. |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
60 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
61 | ``@`` | Significant digit |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
62 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
63 | ``#`` | Digit, zero shows as absent |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
64 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
65 | ``.`` | Decimal separator or monetary decimal separator |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
66 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
67 | ``-`` | Minus sign |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
68 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
69 | ``,`` | Grouping separator |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
70 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
71 | ``E`` | Separates mantissa and exponent in scientific notation |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
72 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
73 | ``+`` | Prefix positive exponents with localized plus sign |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
74 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
75 | ``;`` | Separates positive and negative subpatterns |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
76 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
77 | ``%`` | Multiply by 100 and show as percentage |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
78 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
79 | ``‰`` | Multiply by 1000 and show as per mille |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
80 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
81 | ``¤`` | Currency sign, replaced by currency symbol. If doubled, |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
82 | | replaced by international currency symbol. If tripled, uses the |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
83 | | long form of the decimal symbol. |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
84 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
85 | ``'`` | Used to quote special characters in a prefix or suffix |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
86 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
87 | ``*`` | Pad escape, precedes pad character |
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
88 +----------+-----------------------------------------------------------------+
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
89
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
90
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
91 Parsing Numbers
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
92 ===============
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
93
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
94 Babel can also parse numeric data in a locale-sensitive manner:
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
95
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
96 .. code-block:: pycon
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
97
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
98 >>> from babel.numbers import parse_decimal, parse_number
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
99
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
100 Examples:
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
101
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
102 .. code-block:: pycon
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
103
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
104 >>> parse_decimal('1,099.98', locale='en_US')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
105 1099.98
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
106 >>> parse_decimal('1.099,98', locale='de')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
107 1099.98
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
108 >>> parse_decimal('2,109,998', locale='de')
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
109 Traceback (most recent call last):
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
110 ...
98dcabc99308 Split docs on date and number formatting.
cmlenz
parents:
diff changeset
111 NumberFormatError: '2,109,998' is not a valid decimal number
255
f9f6f740b595 Added examples for using `get_timezone_name` to documentation.
cmlenz
parents: 124
diff changeset
112
f9f6f740b595 Added examples for using `get_timezone_name` to documentation.
cmlenz
parents: 124
diff changeset
113 .. note:: Number parsing is not properly implemented yet
Copyright (C) 2012-2017 Edgewall Software