Commit | Line | Data |
---|---|---|
6a1aa64f DV |
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"> | |
3 | ||
4 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
5 | <head> | |
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> | |
9 | ||
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> | |
13 | </head> | |
14 | <body> | |
15 | <div class="document"> | |
16 | <div class="section"> | |
17 | <h1><a id="name" name="name">Name</a></h1> | |
18 | <p>MochiKit.Format - string formatting goes here</p> | |
19 | </div> | |
20 | <div class="section"> | |
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" ); | |
31 | </pre> | |
32 | </div> | |
33 | <div class="section"> | |
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> | |
37 | </div> | |
38 | <div class="section"> | |
39 | <h1><a id="dependencies" name="dependencies">Dependencies</a></h1> | |
40 | <p>None.</p> | |
41 | </div> | |
42 | <div class="section"> | |
43 | <h1><a id="overview" name="overview">Overview</a></h1> | |
44 | <div class="section"> | |
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"> | |
53 | <colgroup> | |
54 | <col width="15%" /> | |
55 | <col width="85%" /> | |
56 | </colgroup> | |
57 | <thead valign="bottom"> | |
58 | <tr><th class="head">Symbol</th> | |
59 | <th class="head">Meaning</th> | |
60 | </tr> | |
61 | </thead> | |
62 | <tbody valign="top"> | |
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> | |
67 | </tr> | |
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 | |
70 | padding.</td> | |
71 | </tr> | |
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> | |
76 | </tr> | |
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> | |
82 | </tr> | |
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> | |
89 | </tr> | |
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> | |
93 | </tr> | |
94 | </tbody> | |
95 | </table> | |
96 | </div> | |
97 | </div> | |
98 | <div class="section"> | |
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> | |
102 | <p> | |
103 | <a name="fn-formatlocale"></a> | |
104 | <a class="mochidef reference" href="#fn-formatlocale">formatLocale(locale="default")</a>:</p> | |
105 | <blockquote> | |
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> | |
114 | </dl> | |
115 | </blockquote> | |
116 | <p> | |
117 | <a name="fn-lstrip"></a> | |
118 | <a class="mochidef reference" href="#fn-lstrip">lstrip(str, chars="\s")</a>:</p> | |
119 | <blockquote> | |
120 | <p>Returns a string based on <tt class="docutils literal"><span class="pre">str</span></tt> with leading whitespace | |
121 | stripped.</p> | |
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> | |
128 | </dl> | |
129 | </blockquote> | |
130 | <p> | |
131 | <a name="fn-numberformatter"></a> | |
132 | <a class="mochidef reference" href="#fn-numberformatter">numberFormatter(pattern, placeholder="", locale="default")</a>:</p> | |
133 | <blockquote> | |
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 | |
136 | locale.</p> | |
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"> | |
142 | <colgroup> | |
143 | <col width="16%" /> | |
144 | <col width="84%" /> | |
145 | </colgroup> | |
146 | <tbody valign="top"> | |
147 | <tr><td>separator</td> | |
148 | <td>The "thousands" separator for this locale (en_US is ",")</td> | |
149 | </tr> | |
150 | <tr><td>decimal</td> | |
151 | <td>The decimal separator for this locale (en_US is ".")</td> | |
152 | </tr> | |
153 | <tr><td>percent</td> | |
154 | <td>The percent symbol for this locale (en_US is "%")</td> | |
155 | </tr> | |
156 | </tbody> | |
157 | </table> | |
158 | <dl class="docutils"> | |
159 | <dt><em>Availability</em>:</dt> | |
160 | <dd>Available in MochiKit 1.3.1+</dd> | |
161 | </dl> | |
162 | </blockquote> | |
163 | <p> | |
164 | <a name="fn-percentformat"></a> | |
165 | <a class="mochidef reference" href="#fn-percentformat">percentFormat(someFloat)</a>:</p> | |
166 | <blockquote> | |
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> | |
173 | </dl> | |
174 | </blockquote> | |
175 | <p> | |
176 | <a name="fn-roundtofixed"></a> | |
177 | <a class="mochidef reference" href="#fn-roundtofixed">roundToFixed(aNumber, precision)</a>:</p> | |
178 | <blockquote> | |
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> | |
191 | </dl> | |
192 | </blockquote> | |
193 | <p> | |
194 | <a name="fn-rstrip"></a> | |
195 | <a class="mochidef reference" href="#fn-rstrip">rstrip(str, chars="\s")</a>:</p> | |
196 | <blockquote> | |
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> | |
204 | </dl> | |
205 | </blockquote> | |
206 | <p> | |
207 | <a name="fn-strip"></a> | |
208 | <a class="mochidef reference" href="#fn-strip">strip(str, chars="\s")</a>:</p> | |
209 | <blockquote> | |
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> | |
219 | </dl> | |
220 | </blockquote> | |
221 | <p> | |
222 | <a name="fn-trunctofixed"></a> | |
223 | <a class="mochidef reference" href="#fn-trunctofixed">truncToFixed(aNumber, precision)</a>:</p> | |
224 | <blockquote> | |
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> | |
236 | </dl> | |
237 | </blockquote> | |
238 | <p> | |
239 | <a name="fn-twodigitaverage"></a> | |
240 | <a class="mochidef reference" href="#fn-twodigitaverage">twoDigitAverage(numerator, denominator)</a>:</p> | |
241 | <blockquote> | |
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> | |
248 | </dl> | |
249 | </blockquote> | |
250 | <p> | |
251 | <a name="fn-twodigitfloat"></a> | |
252 | <a class="mochidef reference" href="#fn-twodigitfloat">twoDigitFloat(someFloat)</a>:</p> | |
253 | <blockquote> | |
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> | |
260 | </dl> | |
261 | </blockquote> | |
262 | </div> | |
263 | </div> | |
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> | |
268 | <tbody valign="top"> | |
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> | |
271 | </tbody> | |
272 | </table> | |
273 | </div> | |
274 | <div class="section"> | |
275 | <h1><a id="authors" name="authors">Authors</a></h1> | |
276 | <ul class="simple"> | |
277 | <li>Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>></li> | |
278 | </ul> | |
279 | </div> | |
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 | |
285 | v2.1</a>.</p> | |
286 | </div> | |
287 | </div> | |
288 | ||
289 | </body> | |
290 | </html> |