.. title:: MochiKit.Format - string formatting goes here
Name
====
MochiKit.Format - string formatting goes here
Synopsis
========
::
assert( truncToFixed(0.12345, 4) == "0.1234" );
assert( roundToFixed(0.12345, 4) == "0.1235" );
assert( twoDigitAverage(1, 0) == "0" );
assert( twoDigitFloat(1.2345) == "1.23" );
assert( twoDigitFloat(1) == "1" );
assert( percentFormat(1.234567) == "123.46%" );
assert( numberFormatter("###,###%")(125) == "12,500%" );
assert( numberFormatter("##.000")(1.25) == "1.250" );
Description
===========
Formatting strings and stringifying numbers is boring, so a couple
useful functions in that domain live here.
Dependencies
============
None.
Overview
========
Formatting Numbers
------------------
MochiKit provides an extensible number formatting facility, modeled
loosely after the Number Format Pattern Syntax [1]_ from Java.
:mochiref:`numberFormatter(pattern[, placeholder=""[,
locale="default"])` returns a function that converts Number to string
using the given information. ``pattern`` is a string consisting of
the following symbols:
+-----------+---------------------------------------------------------------+
| Symbol | Meaning |
+===========+===============================================================+
| ``-`` | If given, used as the position of the minus sign |
| | for negative numbers. If not given, the position |
| | to the left of the first number placeholder is used. |
+-----------+---------------------------------------------------------------+
| ``#`` | The placeholder for a number that does not imply zero |
| | padding. |
+-----------+---------------------------------------------------------------+
| ``0`` | The placeholder for a number that implies zero padding. |
| | If it is used to the right of a decimal separator, it |
| | implies trailing zeros, otherwise leading zeros. |
+-----------+---------------------------------------------------------------+
| ``,`` | The placeholder for a "thousands separator". May be used |
| | at most once, and it must be to the left of a decimal |
| | separator. Will be replaced by ``locale.separator`` in the |
| | result (the default is also ``,``). |
+-----------+---------------------------------------------------------------+
| ``.`` | The decimal separator. The quantity of ``#`` or ``0`` |
| | after the decimal separator will determine the precision of |
| | the result. If no decimal separator is present, the |
| | fractional precision is ``0`` -- meaning that it will be |
| | rounded to the nearest integer. |
+-----------+---------------------------------------------------------------+
| ``%`` | If present, the number will be multiplied by ``100`` and |
| | the ``%`` will be replaced by ``locale.percent``. |
+-----------+---------------------------------------------------------------+
API Reference
=============
Functions
---------
:mochidef:`formatLocale(locale="default")`:
Return a locale object for the given locale. ``locale`` may be
either a string, which is looked up in the
``MochiKit.Format.LOCALE`` object, or a locale object. If no
locale is given, ``LOCALE.default`` is used (equivalent to
``LOCALE.en_US``).
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`lstrip(str, chars="\\s")`:
Returns a string based on ``str`` with leading whitespace
stripped.
If ``chars`` is given, then that expression will be used instead
of whitespace. ``chars`` should be a string suitable for use in a
``RegExp`` ``[character set]``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`numberFormatter(pattern, placeholder="", locale="default")`:
Return a function ``formatNumber(aNumber)`` that formats numbers
as a string according to the given pattern, placeholder and
locale.
``pattern`` is a string that describes how the numbers should be
formatted, for more information see `Formatting Numbers`_.
``locale`` is a string of a known locale (en_US, de_DE, fr_FR,
default) or an object with the following fields:
+-----------+-----------------------------------------------------------+
| separator | The "thousands" separator for this locale (en_US is ",") |
+-----------+-----------------------------------------------------------+
| decimal | The decimal separator for this locale (en_US is ".") |
+-----------+-----------------------------------------------------------+
| percent | The percent symbol for this locale (en_US is "%") |
+-----------+-----------------------------------------------------------+
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`percentFormat(aNumber)`:
Return a string representation of ``aNumber * 100``, rounded to a
maximum precision of 2 fractional digits. Roughly equivalent to:
``sprintf("%.2f%%", aNumber * 100)``
In new code, you probably want to use:
:mochiref:`numberFormatter("#.##%")(aNumber)` instead.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`roundToFixed(aNumber, precision)`:
Return a string representation of ``aNumber``, rounded to
``precision`` digits with trailing zeros. This is similar to
``Number.toFixed(aNumber, precision)``, but this has
implementation consistent rounding behavior (some versions of
Safari round 0.5 down!) and also includes preceding ``0`` for
numbers less than ``1`` (Safari, again).
For example, :mochiref:`roundToFixed(0.1357, 2)` returns ``0.14``
on every supported platform, where some return ``.13`` for
``(0.1357).toFixed(2)``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`rstrip(str, chars="\\s")`:
Returns a string based on ``str`` with trailing whitespace stripped.
If ``chars`` is given, then that expression will be used instead
of whitespace. ``chars`` should be a string suitable for use in a
``RegExp`` ``[character set]``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`strip(str, chars="\\s")`:
Returns a string based on ``str`` with leading and trailing
whitespace stripped (equivalent to :mochiref:`lstrip(rstrip(str,
chars), chars)`).
If ``chars`` is given, then that expression will be used instead
of whitespace. ``chars`` should be a string suitable for use in a
``RegExp`` ``[character set]``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`truncToFixed(aNumber, precision)`:
Return a string representation of ``aNumber``, truncated to
``precision`` digits with trailing zeros. This is similar to
``aNumber.toFixed(precision)``, but this truncates rather than
rounds and has implementation consistent behavior for numbers less
than 1. Specifically, :mochiref:`truncToFixed(aNumber,
precision)` will always have a preceding ``0`` for numbers less
than ``1``.
For example, :mochiref:`truncToFixed(0.1357, 2)` returns ``0.13``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`twoDigitAverage(numerator, denominator)`:
Calculate an average from a numerator and a denominator and return
it as a string rounded to a maximum precision of two fractional
digits (e.g. "1.23").
If the denominator is 0, "0" will be returned instead of ``NaN``.
*Availability*:
Available in MochiKit 1.3.1+
:mochidef:`twoDigitFloat(aNumber)`:
Return a string representation of ``aNumber``, rounded to a maximum
precision of 2 fractional digits. This is a variation of
:mochiref:`roundToFixed(aNumber, 2)` that removes trailing zeros from
the fractional part.
For example, ``twoDigitFloat(0.1357)`` returns ``0.14``
and ``twoDigitFloat(12.00)`` returns ``12``.
In new code, you probably want to use:
:mochiref:`numberFormatter("#.##")(aNumber)` instead.
*Availability*:
Available in MochiKit 1.3.1+
See Also
========
.. [1] Java Number Format Pattern Syntax:
http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html
Authors
=======
- Bob Ippolito <bob@redivi.com>
Copyright
=========
Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
dual-licensed free software; you can redistribute it and/or modify it
under the terms of the `MIT License`_ or the `Academic Free License
v2.1`_.
.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php
