[dygraphs.git] / mochikit_v14 / doc / rst / MochiKit / Format.rst

.. 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(someFloat)`:

    Roughly equivalent to: ``sprintf("%.2f%%", someFloat * 100)``

    In new code, you probably want to use:
    :mochiref:`numberFormatter("#.##%")(someFloat)` 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 with two digits of precision (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(someFloat)`:

    Roughly equivalent to: ``sprintf("%.2f", someFloat)``

    In new code, you probably want to use
    :mochiref:`numberFormatter("#.##")(someFloat)` 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
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