1 .. title:: MochiKit.Format - string formatting goes here
6 MochiKit.Format - string formatting goes here
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" );
27 Formatting strings and stringifying numbers is boring, so a couple
28 useful functions in that domain live here.
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:
50 +-----------+---------------------------------------------------------------+
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 |
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 +-----------+---------------------------------------------------------------+
86 :mochidef:`formatLocale(locale="default")`:
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
95 Available in MochiKit 1.3.1+
98 :mochidef:`lstrip(str, chars="\\s")`:
100 Returns a string based on ``str`` with leading whitespace
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]``.
108 Available in MochiKit 1.3.1+
111 :mochidef:`numberFormatter(pattern, placeholder="", locale="default")`:
113 Return a function ``formatNumber(aNumber)`` that formats numbers
114 as a string according to the given pattern, placeholder and
117 ``pattern`` is a string that describes how the numbers should be
118 formatted, for more information see `Formatting Numbers`_.
120 ``locale`` is a string of a known locale (en_US, de_DE, fr_FR,
121 default) or an object with the following fields:
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 +-----------+-----------------------------------------------------------+
132 Available in MochiKit 1.3.1+
135 :mochidef:`percentFormat(someFloat)`:
137 Roughly equivalent to: ``sprintf("%.2f%%", someFloat * 100)``
139 In new code, you probably want to use:
140 :mochiref:`numberFormatter("#.##%")(someFloat)` instead.
143 Available in MochiKit 1.3.1+
146 :mochidef:`roundToFixed(aNumber, precision)`:
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).
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)``.
160 Available in MochiKit 1.3.1+
163 :mochidef:`rstrip(str, chars="\\s")`:
165 Returns a string based on ``str`` with trailing whitespace stripped.
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]``.
172 Available in MochiKit 1.3.1+
175 :mochidef:`strip(str, chars="\\s")`:
177 Returns a string based on ``str`` with leading and trailing
178 whitespace stripped (equivalent to :mochiref:`lstrip(rstrip(str,
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]``.
186 Available in MochiKit 1.3.1+
189 :mochidef:`truncToFixed(aNumber, precision)`:
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
199 For example, :mochiref:`truncToFixed(0.1357, 2)` returns ``0.13``.
202 Available in MochiKit 1.3.1+
205 :mochidef:`twoDigitAverage(numerator, denominator)`:
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").
210 If the denominator is 0, "0" will be returned instead of ``NaN``.
213 Available in MochiKit 1.3.1+
216 :mochidef:`twoDigitFloat(someFloat)`:
218 Roughly equivalent to: ``sprintf("%.2f", someFloat)``
220 In new code, you probably want to use
221 :mochiref:`numberFormatter("#.##")(someFloat)` instead.
224 Available in MochiKit 1.3.1+
230 .. [1] Java Number Format Pattern Syntax:
231 http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html
237 - Bob Ippolito <bob@redivi.com>
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
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