| 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 |