mochikit_v14/doc/rst/MochiKit/Format.rst

   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