ceph/src/boost/libs/locale/doc/html/formatting_and_parsing.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   6 <meta name="generator" content="Doxygen 1.8.6"/>
   7 <title>Boost.Locale: Numbers, Time and Currency formatting and parsing</title>
   8 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   9 <script type="text/javascript" src="jquery.js"></script>
  10 <script type="text/javascript" src="dynsections.js"></script>
  11 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  12 <script type="text/javascript" src="resize.js"></script>
  13 <script type="text/javascript" src="navtree.js"></script>
  14 <script type="text/javascript">
  15   $(document).ready(initResizable);
  16   $(window).load(resizeHeight);
  17 </script>
  18 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  19 </head>
  20 <body>
  21 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  22 <div id="titlearea">
  23 <table cellspacing="0" cellpadding="0">
  24  <tbody>
  25  <tr style="height: 56px;">
  26   <td id="projectlogo"><img alt="Logo" src="boost-small.png"/></td>
  27   <td style="padding-left: 0.5em;">
  28    <div id="projectname">Boost.Locale
  29    </div>
  30   </td>
  31  </tr>
  32  </tbody>
  33 </table>
  34 </div>
  35 <!-- end header part -->
  36 <!-- Generated by Doxygen 1.8.6 -->
  37   <div id="navrow1" class="tabs">
  38     <ul class="tablist">
  39       <li><a href="index.html"><span>Main&#160;Page</span></a></li>
  40       <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
  41       <li><a href="modules.html"><span>Modules</span></a></li>
  42       <li><a href="namespaces.html"><span>Namespaces</span></a></li>
  43       <li><a href="annotated.html"><span>Classes</span></a></li>
  44       <li><a href="files.html"><span>Files</span></a></li>
  45       <li><a href="examples.html"><span>Examples</span></a></li>
  46     </ul>
  47   </div>
  48 </div><!-- top -->
  49 <div id="side-nav" class="ui-resizable side-nav-resizable">
  50   <div id="nav-tree">
  51     <div id="nav-tree-contents">
  52       <div id="nav-sync" class="sync"></div>
  53     </div>
  54   </div>
  55   <div id="splitbar" style="-moz-user-select:none;"
  56        class="ui-resizable-handle">
  57   </div>
  58 </div>
  59 <script type="text/javascript">
  60 $(document).ready(function(){initNavTree('formatting_and_parsing.html','');});
  61 </script>
  62 <div id="doc-content">
  63 <div class="header">
  64   <div class="headertitle">
  65 <div class="title">Numbers, Time and Currency formatting and parsing </div>  </div>
  66 </div><!--header-->
  67 <div class="contents">
  68 <div class="textblock"><p>All formatting and parsing is performed via the standard I/O streams. Each of the above information types is represented as a number. The formatting information is set using iostream manipulators. All manipulators are placed in the <a class="el" href="namespaceboost_1_1locale_1_1as.html" title="This namespace includes all manipulators that can be used on IO streams. ">boost::locale::as</a> namespace.</p>
  69 <p>For example:</p>
  70 <div class="fragment"><div class="line">cout &lt;&lt; <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> &lt;&lt; 123.45 &lt;&lt; endl;</div>
  71 <div class="line"><span class="comment">// display 123.45 in local currency representation.</span></div>
  72 <div class="line">cin &gt;&gt; <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> &gt;&gt; x ;</div>
  73 <div class="line"><span class="comment">// Parse currency representation and store it in x</span></div>
  74 </div><!-- fragment --><p>There is a special manipulator <code>as::posix</code> that "unsets" locale-specific settings and returns them to the default <code>iostream</code> formatting and parsing methods. Please note, such formats may still be localized by the default <code>std::num_put</code> and <code>std::num_get</code> facets.</p>
  75 <h1><a class="anchor" id="numbers_formatting"></a>
  76 Numbers and number manipulators</h1>
  77 <p>Here are the manipulators for number formatting:</p>
  78 <ul>
  79 <li><code>as::number</code> &ndash; format number according to local specifications, it takes into account various <code>std::ios_base</code> flags like scientific format and precision. <br/>
  80 </li>
  81 <li><code>as::percent</code> &ndash; format number as "percent" format. For example: <div class="fragment"><div class="line">cout &lt;&lt; <a class="code" href="group__manipulators.html#ga365767c66c9c82fb646458f5eace8534">as::percent</a> &lt;&lt; 0.25 &lt;&lt;endl;</div>
  82 </div><!-- fragment --> Would create an output that may look like this: <pre class="fragment">    25%</pre> <br/>
  83 </li>
  84 <li><code>as::spellout</code> &ndash; spell the number. For example, under the English locale, 103 may be displayed as "one hundred three". <b>Note:</b> not all locales provide rules for spelling numbers. In such a case the number would be displayed in decimal format. <br/>
  85 </li>
  86 <li><code>as::ordinal</code> &ndash; display an order-of element. For example "2" would be displayed as "2nd" under the English locale. As in the above case, not all locales provide ordinal rules.</li>
  87 </ul>
  88 <h1><a class="anchor" id="currency_formatting"></a>
  89 Currency formatting</h1>
  90 <p>These are the manipulators for currency formatting:</p>
  91 <ul>
  92 <li><code>as::currency</code> &ndash; set the format to currency mode.</li>
  93 <li><code>as::currency_iso</code> &ndash; change the currency format to international, like "USD" instead of "$". This flag is supported when using ICU 4.2 and above.</li>
  94 <li><code>as::currency_national</code> &ndash; change currency format to national, like "$".</li>
  95 <li><code>as::currency_default</code> &ndash; return to the default (national) currency format.</li>
  96 </ul>
  97 <dl class="section note"><dt>Note</dt><dd><code>as::currency_XYZ</code> manipulators have no effect on general formatting, only on the currency format. You must use both currency and number manipulators to use a non-default format.</dd></dl>
  98 <h1><a class="anchor" id="date_and_time_formatting"></a>
  99 Date and Time formatting</h1>
 100 <p>Dates and times are represented as POSIX time. When date-time formatting is turned on in the <code>iostream</code>, each number is treated as a POSIX time. The number may be an integer or a double.</p>
 101 <p>There are four major manipulators for Date and Time formatting:</p>
 102 <ul>
 103 <li><code>as::date</code> &ndash; date only</li>
 104 <li><code>as::time</code> &ndash; time only</li>
 105 <li><code>as::datetime</code> &ndash; both date and time</li>
 106 <li><code>as::ftime</code> &ndash; parameterized manipulator that allows specification of time in the format that is used in the <code>strftime</code> function. <b>Note:</b> not all formatting flags of <code>strftime</code> are supported.</li>
 107 </ul>
 108 <p>For example:</p>
 109 <div class="fragment"><div class="line">time_t now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0);</div>
 110 <div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Today is &quot;</span>&lt;&lt; <a class="code" href="group__manipulators.html#gae05b82e6658dc573521518fed5f5c77f">as::date</a> &lt;&lt; now &lt;&lt; <span class="stringliteral">&quot; and tomorrow is &quot;</span> &lt;&lt; now+24*3600 &lt;&lt; endl;</div>
 111 <div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Current time is &quot;</span>&lt;&lt; <a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">as::time</a> &lt;&lt; now &lt;&lt; endl;</div>
 112 <div class="line">cout &lt;&lt; <span class="stringliteral">&quot;The current weekday is &quot;</span>&lt;&lt; <a class="code" href="group__manipulators.html#ga84cc8985e5305ef54394e84c10223866">as::ftime</a>(<span class="stringliteral">&quot;%A&quot;</span>) &lt;&lt; now &lt;&lt; endl;</div>
 113 </div><!-- fragment --><p>More fine-grained control of date-time formatting is also available:</p>
 114 <ul>
 115 <li><code>as::time_default</code> , <code>as::time_short</code> , <code>as::time_medium</code> , <code>as::time_long</code> , <code>as::time_full</code> &ndash; change time formatting.</li>
 116 <li><code>as::date_default</code> , <code>as::date_short</code> , <code>as::date_medium</code> , <code>as::date_long</code> , <code>as::date_full</code> &ndash; change date formatting.</li>
 117 </ul>
 118 <p>These manipulators, when used together with the <code>as::date</code>, <code>as::time</code>, or <code>as::datetime</code> manipulators, change the date-time representation. The default format is medium.</p>
 119 <p>By default, the date and time are shown in the local time zone. This behavior may be changed with the following manipulators:</p>
 120 <ul>
 121 <li><code>as::gmt</code> &ndash; display date and time in GMT.</li>
 122 <li><code>as::local_time</code> &ndash; display in local time zone (default).</li>
 123 <li><code>as::time_zone</code> &ndash; parameterized manipulator that sets the time-zone ID for date-time formatting and parsing. It takes a string parameter that represents the time zone ID.</li>
 124 </ul>
 125 <p>For example:</p>
 126 <div class="fragment"><div class="line"><span class="keywordtype">double</span> now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0);</div>
 127 <div class="line">cout &lt;&lt; <a class="code" href="group__manipulators.html#ga820edf843e20847a0c4ccb8da0c4acd8">as::datetime</a> &lt;&lt; <a class="code" href="group__manipulators.html#gac6cb5458543daf651cd6b48812891541">as::local_time</a> &lt;&lt; <span class="stringliteral">&quot;Local time is: &quot;</span>&lt;&lt; now &lt;&lt; endl;</div>
 128 <div class="line">cout &lt;&lt; <a class="code" href="group__manipulators.html#gac90c969d876305b8584def8632ae1808">as::gmt</a> &lt;&lt; <span class="stringliteral">&quot;GMT Time is: &quot;</span>&lt;&lt; now &lt;&lt;endl;</div>
 129 <div class="line">cout &lt;&lt; <a class="code" href="group__manipulators.html#gad51fbdc634fe0c81e5183915e9eeb238">as::time_zone</a>(<span class="stringliteral">&quot;EST&quot;</span>) &lt;&lt; <span class="stringliteral">&quot;Eastern Standard Time is: &quot;</span>&lt;&lt; now &lt;&lt;endl;</div>
 130 </div><!-- fragment --><p>There is a list of supported <code>strftime</code> flags by ICU backend:</p>
 131 <ul>
 132 <li><code>%a</code> &ndash; Abbreviated weekday (Sun.)</li>
 133 <li><code>%A</code> &ndash; Full weekday (Sunday)</li>
 134 <li><code>%b</code> &ndash; Abbreviated month (Jan.)</li>
 135 <li><code>%B</code> &ndash; Full month (January)</li>
 136 <li><code>%c</code> &ndash; Locale date-time format. <b>Note:</b> prefer using <code>as::datetime</code> </li>
 137 <li><code>%d</code> &ndash; Day of Month [01,31]</li>
 138 <li><code>%e</code> &ndash; Day of Month [1,31]</li>
 139 <li><code>%h</code> &ndash; Same as <code>%b</code> </li>
 140 <li><code>%H</code> &ndash; 24 clock hour [00,23]</li>
 141 <li><code>%I</code> &ndash; 12 clock hour [01,12]</li>
 142 <li><code>%j</code> &ndash; Day of year [1,366]</li>
 143 <li><code>%m</code> &ndash; Month [01,12]</li>
 144 <li><code>%M</code> &ndash; Minute [00,59]</li>
 145 <li><code>%n</code> &ndash; New Line</li>
 146 <li><code>%p</code> &ndash; AM/PM in locale representation</li>
 147 <li><code>%r</code> &ndash; Time with AM/PM, same as <code>%I:%M:%S</code> %p</li>
 148 <li><code>%R</code> &ndash; Same as <code>%H:%M</code> </li>
 149 <li><code>%S</code> &ndash; Second [00,61]</li>
 150 <li><code>%t</code> &ndash; Tab character</li>
 151 <li><code>%T</code> &ndash; Same as <code>%H:%M:%S</code> </li>
 152 <li><code>%x</code> &ndash; Local date representation. <b>Note:</b> prefer using <code>as::date</code> </li>
 153 <li><code>%X</code> &ndash; Local time representation. <b>Note:</b> prefer using <code>as::time</code> </li>
 154 <li><code>%y</code> &ndash; Year [00,99]</li>
 155 <li><code>%Y</code> &ndash; 4 digits year. (2009)</li>
 156 <li><code>%Z</code> &ndash; Time Zone</li>
 157 <li><code>%%</code> &ndash; Percent symbol</li>
 158 </ul>
 159 <p>Unsupported <code>strftime</code> flags are: <code>%C</code> , <code>%u</code> , <code>%U</code> , <code>%V</code> , <code>%w</code> , <code>%W</code> . Also, the <code>O</code> and <code>E</code> modifiers are not supported.</p>
 160 <p><b>General</b> <b>recommendations</b> </p>
 161 <ul>
 162 <li>Prefer using generic date-time manipulators rather than specifying the full format using <code>as::ftime</code>.</li>
 163 <li>Remember that current calendars may be not Gregorian.</li>
 164 </ul>
 165 <h1><a class="anchor" id="formatting_internals"></a>
 166 Internals</h1>
 167 <p>Formatting information is stored in a stream class by using the <code>xalloc</code>, <code>pword</code>, and <code>register_callback</code> member functions of <code>std::ios_base</code> . All the information is stored and managed using a special object bound to <code>iostream</code>, and the manipulators just change its state.</p>
 168 <p>When a number is written to or read from the stream, a custom Boost.Locale facet accesses the object and checks the required formatting information. Then it creates a special object that actually formats the number and caches it in the <code>iostream</code>. The next time a number is written to the stream, the same formatter would be used unless some flags had changed and formatter object is invalid. </p>
 169 </div></div><!-- contents -->
 170 </div><!-- doc-content -->
 171
 172     <li class="footer">
 173 &copy; Copyright 2009-2012 Artyom Beilis,  Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License</a>, Version 1.0.
 174     </li>
 175    </ul>
 176  </div>
 177 </body>
 178 </html>