mochikit_v14/doc/html/MochiKit/Format.html

   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) == &quot;0.1234&quot; );
  24 assert( roundToFixed(0.12345, 4) == &quot;0.1235&quot; );
  25 assert( twoDigitAverage(1, 0) == &quot;0&quot; );
  26 assert( twoDigitFloat(1.2345) == &quot;1.23&quot; );
  27 assert( twoDigitFloat(1) == &quot;1&quot; );
  28 assert( percentFormat(1.234567) == &quot;123.46%&quot; );
  29 assert( numberFormatter(&quot;###,###%&quot;)(125) == &quot;12,500%&quot; );
  30 assert( numberFormatter(&quot;##.000&quot;)(1.25) == &quot;1.250&quot; );
  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=&quot;&quot;[,
  49 locale=&quot;default&quot;])</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 &quot;thousands separator&quot;. 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=&quot;default&quot;)</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=&quot;\s&quot;)</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=&quot;&quot;, locale=&quot;default&quot;)</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 &quot;thousands&quot; separator for this locale (en_US is &quot;,&quot;)</td>
 149 </tr>
 150 <tr><td>decimal</td>
 151 <td>The decimal separator for this locale (en_US is &quot;.&quot;)</td>
 152 </tr>
 153 <tr><td>percent</td>
 154 <td>The percent symbol for this locale (en_US is &quot;%&quot;)</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(&quot;%.2f%%&quot;,</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(&quot;#.##%&quot;)(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=&quot;\s&quot;)</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=&quot;\s&quot;)</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. &quot;1.23&quot;).</p>
 244 <p>If the denominator is 0, &quot;0&quot; 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(&quot;%.2f&quot;,</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(&quot;#.##&quot;)(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 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;</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 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;. 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>