1 <?xml version=
"1.0" encoding=
"utf-8" ?>
2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en" lang=
"en">
6 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8" />
7 <meta name=
"generator" content=
"Docutils 0.4: http://docutils.sourceforge.net/" />
8 <title>MochiKit.Format - string formatting goes here
</title>
10 <link rel=
"stylesheet" href=
"../../../include/css/documentation.css" type=
"text/css" />
11 <script type=
"text/javascript" src=
"../../../packed/MochiKit/MochiKit.js"></script>
12 <script type=
"text/javascript" src=
"../../js/toc.js"></script>
15 <div class=
"document">
17 <h1><a id=
"name" name=
"name">Name
</a></h1>
18 <p>MochiKit.Format - string formatting goes here
</p>
21 <h1><a id=
"synopsis" name=
"synopsis">Synopsis
</a></h1>
22 <pre class=
"literal-block">
23 assert( truncToFixed(
0.12345,
4) ==
"0.1234" );
24 assert( roundToFixed(
0.12345,
4) ==
"0.1235" );
25 assert( twoDigitAverage(
1,
0) ==
"0" );
26 assert( twoDigitFloat(
1.2345) ==
"1.23" );
27 assert( twoDigitFloat(
1) ==
"1" );
28 assert( percentFormat(
1.234567) ==
"123.46%
" );
29 assert( numberFormatter(
"###,###%
")(
125) ==
"12,
500%
" );
30 assert( numberFormatter(
"##
.000")(
1.25) ==
"1.250" );
34 <h1><a id=
"description" name=
"description">Description
</a></h1>
35 <p>Formatting strings and stringifying numbers is boring, so a couple
36 useful functions in that domain live here.
</p>
39 <h1><a id=
"dependencies" name=
"dependencies">Dependencies
</a></h1>
43 <h1><a id=
"overview" name=
"overview">Overview
</a></h1>
45 <h2><a id=
"formatting-numbers" name=
"formatting-numbers">Formatting Numbers
</a></h2>
46 <p>MochiKit provides an extensible number formatting facility, modeled
47 loosely after the Number Format Pattern Syntax
<a class=
"footnote-reference" href=
"#id2" id=
"id1" name=
"id1">[
1]
</a> from Java.
48 <a class=
"mochiref reference" href=
"#fn-numberformatter">numberFormatter(pattern[, placeholder=
""[,
49 locale=
"default
"])
</a> returns a function that converts Number to string
50 using the given information.
<tt class=
"docutils literal"><span class=
"pre">pattern
</span></tt> is a string consisting of
51 the following symbols:
</p>
52 <table border=
"1" class=
"docutils">
57 <thead valign=
"bottom">
58 <tr><th class=
"head">Symbol
</th>
59 <th class=
"head">Meaning
</th>
63 <tr><td><tt class=
"docutils literal"><span class=
"pre">-
</span></tt></td>
64 <td>If given, used as the position of the minus sign
65 for negative numbers. If not given, the position
66 to the left of the first number placeholder is used.
</td>
68 <tr><td><tt class=
"docutils literal"><span class=
"pre">#
</span></tt></td>
69 <td>The placeholder for a number that does not imply zero
72 <tr><td><tt class=
"docutils literal"><span class=
"pre">0</span></tt></td>
73 <td>The placeholder for a number that implies zero padding.
74 If it is used to the right of a decimal separator, it
75 implies trailing zeros, otherwise leading zeros.
</td>
77 <tr><td><tt class=
"docutils literal"><span class=
"pre">,
</span></tt></td>
78 <td>The placeholder for a
"thousands separator
". May be used
79 at most once, and it must be to the left of a decimal
80 separator. Will be replaced by
<tt class=
"docutils literal"><span class=
"pre">locale.separator
</span></tt> in the
81 result (the default is also
<tt class=
"docutils literal"><span class=
"pre">,
</span></tt>).
</td>
83 <tr><td><tt class=
"docutils literal"><span class=
"pre">.
</span></tt></td>
84 <td>The decimal separator. The quantity of
<tt class=
"docutils literal"><span class=
"pre">#
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">0</span></tt>
85 after the decimal separator will determine the precision of
86 the result. If no decimal separator is present, the
87 fractional precision is
<tt class=
"docutils literal"><span class=
"pre">0</span></tt> -- meaning that it will be
88 rounded to the nearest integer.
</td>
90 <tr><td><tt class=
"docutils literal"><span class=
"pre">%
</span></tt></td>
91 <td>If present, the number will be multiplied by
<tt class=
"docutils literal"><span class=
"pre">100</span></tt> and
92 the
<tt class=
"docutils literal"><span class=
"pre">%
</span></tt> will be replaced by
<tt class=
"docutils literal"><span class=
"pre">locale.percent
</span></tt>.
</td>
99 <h1><a id=
"api-reference" name=
"api-reference">API Reference
</a></h1>
100 <div class=
"section">
101 <h2><a id=
"functions" name=
"functions">Functions
</a></h2>
103 <a name=
"fn-formatlocale"></a>
104 <a class=
"mochidef reference" href=
"#fn-formatlocale">formatLocale(locale=
"default
")
</a>:
</p>
106 <p>Return a locale object for the given locale.
<tt class=
"docutils literal"><span class=
"pre">locale
</span></tt> may be
107 either a string, which is looked up in the
108 <tt class=
"docutils literal"><span class=
"pre">MochiKit.Format.LOCALE
</span></tt> object, or a locale object. If no
109 locale is given,
<tt class=
"docutils literal"><span class=
"pre">LOCALE.default
</span></tt> is used (equivalent to
110 <tt class=
"docutils literal"><span class=
"pre">LOCALE.en_US
</span></tt>).
</p>
111 <dl class=
"docutils">
112 <dt><em>Availability
</em>:
</dt>
113 <dd>Available in MochiKit
1.3.1+
</dd>
117 <a name=
"fn-lstrip"></a>
118 <a class=
"mochidef reference" href=
"#fn-lstrip">lstrip(str, chars=
"\s
")
</a>:
</p>
120 <p>Returns a string based on
<tt class=
"docutils literal"><span class=
"pre">str
</span></tt> with leading whitespace
122 <p>If
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> is given, then that expression will be used instead
123 of whitespace.
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> should be a string suitable for use in a
124 <tt class=
"docutils literal"><span class=
"pre">RegExp
</span></tt> <tt class=
"docutils literal"><span class=
"pre">[character
</span> <span class=
"pre">set]
</span></tt>.
</p>
125 <dl class=
"docutils">
126 <dt><em>Availability
</em>:
</dt>
127 <dd>Available in MochiKit
1.3.1+
</dd>
131 <a name=
"fn-numberformatter"></a>
132 <a class=
"mochidef reference" href=
"#fn-numberformatter">numberFormatter(pattern, placeholder=
"", locale=
"default
")
</a>:
</p>
134 <p>Return a function
<tt class=
"docutils literal"><span class=
"pre">formatNumber(aNumber)
</span></tt> that formats numbers
135 as a string according to the given pattern, placeholder and
137 <p><tt class=
"docutils literal"><span class=
"pre">pattern
</span></tt> is a string that describes how the numbers should be
138 formatted, for more information see
<a class=
"reference" href=
"#formatting-numbers">Formatting Numbers
</a>.
</p>
139 <p><tt class=
"docutils literal"><span class=
"pre">locale
</span></tt> is a string of a known locale (en_US, de_DE, fr_FR,
140 default) or an object with the following fields:
</p>
141 <table border=
"1" class=
"docutils">
147 <tr><td>separator
</td>
148 <td>The
"thousands
" separator for this locale (en_US is
",
")
</td>
151 <td>The decimal separator for this locale (en_US is
".
")
</td>
154 <td>The percent symbol for this locale (en_US is
"%
")
</td>
158 <dl class=
"docutils">
159 <dt><em>Availability
</em>:
</dt>
160 <dd>Available in MochiKit
1.3.1+
</dd>
164 <a name=
"fn-percentformat"></a>
165 <a class=
"mochidef reference" href=
"#fn-percentformat">percentFormat(someFloat)
</a>:
</p>
167 <p>Roughly equivalent to:
<tt class=
"docutils literal"><span class=
"pre">sprintf(
"%
.2f%%
",
</span> <span class=
"pre">someFloat
</span> <span class=
"pre">*
</span> <span class=
"pre">100)
</span></tt></p>
168 <p>In new code, you probably want to use:
169 <a class=
"mochiref reference" href=
"#fn-numberformatter">numberFormatter(
"#.##%
")(someFloat)
</a> instead.
</p>
170 <dl class=
"docutils">
171 <dt><em>Availability
</em>:
</dt>
172 <dd>Available in MochiKit
1.3.1+
</dd>
176 <a name=
"fn-roundtofixed"></a>
177 <a class=
"mochidef reference" href=
"#fn-roundtofixed">roundToFixed(aNumber, precision)
</a>:
</p>
179 <p>Return a string representation of
<tt class=
"docutils literal"><span class=
"pre">aNumber
</span></tt>, rounded to
180 <tt class=
"docutils literal"><span class=
"pre">precision
</span></tt> digits with trailing zeros. This is similar to
181 <tt class=
"docutils literal"><span class=
"pre">Number.toFixed(aNumber,
</span> <span class=
"pre">precision)
</span></tt>, but this has
182 implementation consistent rounding behavior (some versions of
183 Safari round
0.5 down!) and also includes preceding
<tt class=
"docutils literal"><span class=
"pre">0</span></tt> for
184 numbers less than
<tt class=
"docutils literal"><span class=
"pre">1</span></tt> (Safari, again).
</p>
185 <p>For example,
<a class=
"mochiref reference" href=
"#fn-roundtofixed">roundToFixed(
0.1357,
2)
</a> returns
<tt class=
"docutils literal"><span class=
"pre">0.14</span></tt>
186 on every supported platform, where some return
<tt class=
"docutils literal"><span class=
"pre">.13</span></tt> for
187 <tt class=
"docutils literal"><span class=
"pre">(
0.1357).toFixed(
2)
</span></tt>.
</p>
188 <dl class=
"docutils">
189 <dt><em>Availability
</em>:
</dt>
190 <dd>Available in MochiKit
1.3.1+
</dd>
194 <a name=
"fn-rstrip"></a>
195 <a class=
"mochidef reference" href=
"#fn-rstrip">rstrip(str, chars=
"\s
")
</a>:
</p>
197 <p>Returns a string based on
<tt class=
"docutils literal"><span class=
"pre">str
</span></tt> with trailing whitespace stripped.
</p>
198 <p>If
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> is given, then that expression will be used instead
199 of whitespace.
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> should be a string suitable for use in a
200 <tt class=
"docutils literal"><span class=
"pre">RegExp
</span></tt> <tt class=
"docutils literal"><span class=
"pre">[character
</span> <span class=
"pre">set]
</span></tt>.
</p>
201 <dl class=
"docutils">
202 <dt><em>Availability
</em>:
</dt>
203 <dd>Available in MochiKit
1.3.1+
</dd>
207 <a name=
"fn-strip"></a>
208 <a class=
"mochidef reference" href=
"#fn-strip">strip(str, chars=
"\s
")
</a>:
</p>
210 <p>Returns a string based on
<tt class=
"docutils literal"><span class=
"pre">str
</span></tt> with leading and trailing
211 whitespace stripped (equivalent to
<a class=
"mochiref reference" href=
"#fn-lstrip">lstrip(rstrip(str,
212 chars), chars)
</a>).
</p>
213 <p>If
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> is given, then that expression will be used instead
214 of whitespace.
<tt class=
"docutils literal"><span class=
"pre">chars
</span></tt> should be a string suitable for use in a
215 <tt class=
"docutils literal"><span class=
"pre">RegExp
</span></tt> <tt class=
"docutils literal"><span class=
"pre">[character
</span> <span class=
"pre">set]
</span></tt>.
</p>
216 <dl class=
"docutils">
217 <dt><em>Availability
</em>:
</dt>
218 <dd>Available in MochiKit
1.3.1+
</dd>
222 <a name=
"fn-trunctofixed"></a>
223 <a class=
"mochidef reference" href=
"#fn-trunctofixed">truncToFixed(aNumber, precision)
</a>:
</p>
225 <p>Return a string representation of
<tt class=
"docutils literal"><span class=
"pre">aNumber
</span></tt>, truncated to
226 <tt class=
"docutils literal"><span class=
"pre">precision
</span></tt> digits with trailing zeros. This is similar to
227 <tt class=
"docutils literal"><span class=
"pre">aNumber.toFixed(precision)
</span></tt>, but this truncates rather than
228 rounds and has implementation consistent behavior for numbers less
229 than
1. Specifically,
<a class=
"mochiref reference" href=
"#fn-trunctofixed">truncToFixed(aNumber,
230 precision)
</a> will always have a preceding
<tt class=
"docutils literal"><span class=
"pre">0</span></tt> for numbers less
231 than
<tt class=
"docutils literal"><span class=
"pre">1</span></tt>.
</p>
232 <p>For example,
<a class=
"mochiref reference" href=
"#fn-trunctofixed">truncToFixed(
0.1357,
2)
</a> returns
<tt class=
"docutils literal"><span class=
"pre">0.13</span></tt>.
</p>
233 <dl class=
"docutils">
234 <dt><em>Availability
</em>:
</dt>
235 <dd>Available in MochiKit
1.3.1+
</dd>
239 <a name=
"fn-twodigitaverage"></a>
240 <a class=
"mochidef reference" href=
"#fn-twodigitaverage">twoDigitAverage(numerator, denominator)
</a>:
</p>
242 <p>Calculate an average from a numerator and a denominator and return
243 it as a string with two digits of precision (e.g.
"1.23").
</p>
244 <p>If the denominator is
0,
"0" will be returned instead of
<tt class=
"docutils literal"><span class=
"pre">NaN
</span></tt>.
</p>
245 <dl class=
"docutils">
246 <dt><em>Availability
</em>:
</dt>
247 <dd>Available in MochiKit
1.3.1+
</dd>
251 <a name=
"fn-twodigitfloat"></a>
252 <a class=
"mochidef reference" href=
"#fn-twodigitfloat">twoDigitFloat(someFloat)
</a>:
</p>
254 <p>Roughly equivalent to:
<tt class=
"docutils literal"><span class=
"pre">sprintf(
"%
.2f
",
</span> <span class=
"pre">someFloat)
</span></tt></p>
255 <p>In new code, you probably want to use
256 <a class=
"mochiref reference" href=
"#fn-numberformatter">numberFormatter(
"#.##
")(someFloat)
</a> instead.
</p>
257 <dl class=
"docutils">
258 <dt><em>Availability
</em>:
</dt>
259 <dd>Available in MochiKit
1.3.1+
</dd>
264 <div class=
"section">
265 <h1><a id=
"see-also" name=
"see-also">See Also
</a></h1>
266 <table class=
"docutils footnote" frame=
"void" id=
"id2" rules=
"none">
267 <colgroup><col class=
"label" /><col /></colgroup>
269 <tr><td class=
"label"><a class=
"fn-backref" href=
"#id1" name=
"id2">[
1]
</a></td><td>Java Number Format Pattern Syntax:
270 <a class=
"reference" href=
"http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html">http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html
</a></td></tr>
274 <div class=
"section">
275 <h1><a id=
"authors" name=
"authors">Authors
</a></h1>
277 <li>Bob Ippolito
<<a class=
"reference" href=
"mailto:bob@redivi.com">bob
@redivi.com
</a>></li>
280 <div class=
"section">
281 <h1><a id=
"copyright" name=
"copyright">Copyright
</a></h1>
282 <p>Copyright
2005 Bob Ippolito
<<a class=
"reference" href=
"mailto:bob@redivi.com">bob
@redivi.com
</a>>. This program is
283 dual-licensed free software; you can redistribute it and/or modify it
284 under the terms of the
<a class=
"reference" href=
"http://www.opensource.org/licenses/mit-license.php">MIT License
</a> or the
<a class=
"reference" href=
"http://www.opensource.org/licenses/afl-2.1.php">Academic Free License