Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | .. title:: MochiKit.Format - string formatting goes here |
2 | ||
3 | Name | |
4 | ==== | |
5 | ||
6 | MochiKit.Format - string formatting goes here | |
7 | ||
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | :: | |
13 | ||
14 | assert( truncToFixed(0.12345, 4) == "0.1234" ); | |
15 | assert( roundToFixed(0.12345, 4) == "0.1235" ); | |
16 | assert( twoDigitAverage(1, 0) == "0" ); | |
17 | assert( twoDigitFloat(1.2345) == "1.23" ); | |
18 | assert( twoDigitFloat(1) == "1" ); | |
19 | assert( percentFormat(1.234567) == "123.46%" ); | |
20 | assert( numberFormatter("###,###%")(125) == "12,500%" ); | |
21 | assert( numberFormatter("##.000")(1.25) == "1.250" ); | |
22 | ||
23 | ||
24 | Description | |
25 | =========== | |
26 | ||
27 | Formatting strings and stringifying numbers is boring, so a couple | |
28 | useful functions in that domain live here. | |
29 | ||
30 | ||
31 | Dependencies | |
32 | ============ | |
33 | ||
34 | None. | |
35 | ||
36 | ||
37 | Overview | |
38 | ======== | |
39 | ||
40 | Formatting Numbers | |
41 | ------------------ | |
42 | ||
43 | MochiKit provides an extensible number formatting facility, modeled | |
44 | loosely after the Number Format Pattern Syntax [1]_ from Java. | |
45 | :mochiref:`numberFormatter(pattern[, placeholder=""[, | |
46 | locale="default"])` returns a function that converts Number to string | |
47 | using the given information. ``pattern`` is a string consisting of | |
48 | the following symbols: | |
49 | ||
50 | +-----------+---------------------------------------------------------------+ | |
51 | | Symbol | Meaning | | |
52 | +===========+===============================================================+ | |
53 | | ``-`` | If given, used as the position of the minus sign | | |
54 | | | for negative numbers. If not given, the position | | |
55 | | | to the left of the first number placeholder is used. | | |
56 | +-----------+---------------------------------------------------------------+ | |
57 | | ``#`` | The placeholder for a number that does not imply zero | | |
58 | | | padding. | | |
59 | +-----------+---------------------------------------------------------------+ | |
60 | | ``0`` | The placeholder for a number that implies zero padding. | | |
61 | | | If it is used to the right of a decimal separator, it | | |
62 | | | implies trailing zeros, otherwise leading zeros. | | |
63 | +-----------+---------------------------------------------------------------+ | |
64 | | ``,`` | The placeholder for a "thousands separator". May be used | | |
65 | | | at most once, and it must be to the left of a decimal | | |
66 | | | separator. Will be replaced by ``locale.separator`` in the | | |
67 | | | result (the default is also ``,``). | | |
68 | +-----------+---------------------------------------------------------------+ | |
69 | | ``.`` | The decimal separator. The quantity of ``#`` or ``0`` | | |
70 | | | after the decimal separator will determine the precision of | | |
71 | | | the result. If no decimal separator is present, the | | |
72 | | | fractional precision is ``0`` -- meaning that it will be | | |
73 | | | rounded to the nearest integer. | | |
74 | +-----------+---------------------------------------------------------------+ | |
75 | | ``%`` | If present, the number will be multiplied by ``100`` and | | |
76 | | | the ``%`` will be replaced by ``locale.percent``. | | |
77 | +-----------+---------------------------------------------------------------+ | |
78 | ||
79 | ||
80 | API Reference | |
81 | ============= | |
82 | ||
83 | Functions | |
84 | --------- | |
85 | ||
86 | :mochidef:`formatLocale(locale="default")`: | |
87 | ||
88 | Return a locale object for the given locale. ``locale`` may be | |
89 | either a string, which is looked up in the | |
90 | ``MochiKit.Format.LOCALE`` object, or a locale object. If no | |
91 | locale is given, ``LOCALE.default`` is used (equivalent to | |
92 | ``LOCALE.en_US``). | |
93 | ||
94 | *Availability*: | |
95 | Available in MochiKit 1.3.1+ | |
96 | ||
97 | ||
98 | :mochidef:`lstrip(str, chars="\\s")`: | |
99 | ||
100 | Returns a string based on ``str`` with leading whitespace | |
101 | stripped. | |
102 | ||
103 | If ``chars`` is given, then that expression will be used instead | |
104 | of whitespace. ``chars`` should be a string suitable for use in a | |
105 | ``RegExp`` ``[character set]``. | |
106 | ||
107 | *Availability*: | |
108 | Available in MochiKit 1.3.1+ | |
109 | ||
110 | ||
111 | :mochidef:`numberFormatter(pattern, placeholder="", locale="default")`: | |
112 | ||
113 | Return a function ``formatNumber(aNumber)`` that formats numbers | |
114 | as a string according to the given pattern, placeholder and | |
115 | locale. | |
116 | ||
117 | ``pattern`` is a string that describes how the numbers should be | |
118 | formatted, for more information see `Formatting Numbers`_. | |
119 | ||
120 | ``locale`` is a string of a known locale (en_US, de_DE, fr_FR, | |
121 | default) or an object with the following fields: | |
122 | ||
123 | +-----------+-----------------------------------------------------------+ | |
124 | | separator | The "thousands" separator for this locale (en_US is ",") | | |
125 | +-----------+-----------------------------------------------------------+ | |
126 | | decimal | The decimal separator for this locale (en_US is ".") | | |
127 | +-----------+-----------------------------------------------------------+ | |
128 | | percent | The percent symbol for this locale (en_US is "%") | | |
129 | +-----------+-----------------------------------------------------------+ | |
130 | ||
131 | *Availability*: | |
132 | Available in MochiKit 1.3.1+ | |
133 | ||
134 | ||
135 | :mochidef:`percentFormat(someFloat)`: | |
136 | ||
137 | Roughly equivalent to: ``sprintf("%.2f%%", someFloat * 100)`` | |
138 | ||
139 | In new code, you probably want to use: | |
140 | :mochiref:`numberFormatter("#.##%")(someFloat)` instead. | |
141 | ||
142 | *Availability*: | |
143 | Available in MochiKit 1.3.1+ | |
144 | ||
145 | ||
146 | :mochidef:`roundToFixed(aNumber, precision)`: | |
147 | ||
148 | Return a string representation of ``aNumber``, rounded to | |
149 | ``precision`` digits with trailing zeros. This is similar to | |
150 | ``Number.toFixed(aNumber, precision)``, but this has | |
151 | implementation consistent rounding behavior (some versions of | |
152 | Safari round 0.5 down!) and also includes preceding ``0`` for | |
153 | numbers less than ``1`` (Safari, again). | |
154 | ||
155 | For example, :mochiref:`roundToFixed(0.1357, 2)` returns ``0.14`` | |
156 | on every supported platform, where some return ``.13`` for | |
157 | ``(0.1357).toFixed(2)``. | |
158 | ||
159 | *Availability*: | |
160 | Available in MochiKit 1.3.1+ | |
161 | ||
162 | ||
163 | :mochidef:`rstrip(str, chars="\\s")`: | |
164 | ||
165 | Returns a string based on ``str`` with trailing whitespace stripped. | |
166 | ||
167 | If ``chars`` is given, then that expression will be used instead | |
168 | of whitespace. ``chars`` should be a string suitable for use in a | |
169 | ``RegExp`` ``[character set]``. | |
170 | ||
171 | *Availability*: | |
172 | Available in MochiKit 1.3.1+ | |
173 | ||
174 | ||
175 | :mochidef:`strip(str, chars="\\s")`: | |
176 | ||
177 | Returns a string based on ``str`` with leading and trailing | |
178 | whitespace stripped (equivalent to :mochiref:`lstrip(rstrip(str, | |
179 | chars), chars)`). | |
180 | ||
181 | If ``chars`` is given, then that expression will be used instead | |
182 | of whitespace. ``chars`` should be a string suitable for use in a | |
183 | ``RegExp`` ``[character set]``. | |
184 | ||
185 | *Availability*: | |
186 | Available in MochiKit 1.3.1+ | |
187 | ||
188 | ||
189 | :mochidef:`truncToFixed(aNumber, precision)`: | |
190 | ||
191 | Return a string representation of ``aNumber``, truncated to | |
192 | ``precision`` digits with trailing zeros. This is similar to | |
193 | ``aNumber.toFixed(precision)``, but this truncates rather than | |
194 | rounds and has implementation consistent behavior for numbers less | |
195 | than 1. Specifically, :mochiref:`truncToFixed(aNumber, | |
196 | precision)` will always have a preceding ``0`` for numbers less | |
197 | than ``1``. | |
198 | ||
199 | For example, :mochiref:`truncToFixed(0.1357, 2)` returns ``0.13``. | |
200 | ||
201 | *Availability*: | |
202 | Available in MochiKit 1.3.1+ | |
203 | ||
204 | ||
205 | :mochidef:`twoDigitAverage(numerator, denominator)`: | |
206 | ||
207 | Calculate an average from a numerator and a denominator and return | |
208 | it as a string with two digits of precision (e.g. "1.23"). | |
209 | ||
210 | If the denominator is 0, "0" will be returned instead of ``NaN``. | |
211 | ||
212 | *Availability*: | |
213 | Available in MochiKit 1.3.1+ | |
214 | ||
215 | ||
216 | :mochidef:`twoDigitFloat(someFloat)`: | |
217 | ||
218 | Roughly equivalent to: ``sprintf("%.2f", someFloat)`` | |
219 | ||
220 | In new code, you probably want to use | |
221 | :mochiref:`numberFormatter("#.##")(someFloat)` instead. | |
222 | ||
223 | *Availability*: | |
224 | Available in MochiKit 1.3.1+ | |
225 | ||
226 | ||
227 | See Also | |
228 | ======== | |
229 | ||
230 | .. [1] Java Number Format Pattern Syntax: | |
231 | http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html | |
232 | ||
233 | ||
234 | Authors | |
235 | ======= | |
236 | ||
237 | - Bob Ippolito <bob@redivi.com> | |
238 | ||
239 | ||
240 | Copyright | |
241 | ========= | |
242 | ||
243 | Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is | |
244 | dual-licensed free software; you can redistribute it and/or modify it | |
245 | under the terms of the `MIT License`_ or the `Academic Free License | |
246 | v2.1`_. | |
247 | ||
248 | .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php | |
249 | .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php |