| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=9"/> |
| <title>Boost.Locale: Numbers, Time and Currency formatting and parsing</title> |
| |
| <link href="tabs.css" rel="stylesheet" type="text/css"/> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| <link href="navtree.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="jquery.js"></script> |
| <script type="text/javascript" src="resize.js"></script> |
| <script type="text/javascript" src="navtree.js"></script> |
| <script type="text/javascript"> |
| $(document).ready(initResizable); |
| </script> |
| |
| |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div! --> |
| |
| |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr style="height: 56px;"> |
| |
| <td id="projectlogo"><img alt="Logo" src="boost-small.png"/></td> |
| |
| |
| <td style="padding-left: 0.5em;"> |
| <div id="projectname">Boost.Locale |
| |
| </div> |
| |
| </td> |
| |
| |
| |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <!-- Generated by Doxygen 1.7.6.1 --> |
| <div id="navrow1" class="tabs"> |
| <ul class="tablist"> |
| <li><a href="index.html"><span>Main Page</span></a></li> |
| <li><a href="modules.html"><span>Modules</span></a></li> |
| <li><a href="namespaces.html"><span>Namespaces</span></a></li> |
| <li><a href="annotated.html"><span>Classes</span></a></li> |
| <li><a href="files.html"><span>Files</span></a></li> |
| <li><a href="examples.html"><span>Examples</span></a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="side-nav" class="ui-resizable side-nav-resizable"> |
| <div id="nav-tree"> |
| <div id="nav-tree-contents"> |
| </div> |
| </div> |
| <div id="splitbar" style="-moz-user-select:none;" |
| class="ui-resizable-handle"> |
| </div> |
| </div> |
| <script type="text/javascript"> |
| initNavTree('formatting_and_parsing.html',''); |
| </script> |
| <div id="doc-content"> |
| <div class="header"> |
| <div class="headertitle"> |
| <div class="title">Numbers, Time and Currency formatting and parsing </div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <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> |
| <p>For example:</p> |
| <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> << 123.45 << endl; |
| <span class="comment">// display 123.45 in local currency representation.</span> |
| cin >> <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> >> x ; |
| <span class="comment">// Parse currency representation and store it in x</span> |
| </pre></div><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> |
| <h2><a class="anchor" id="numbers_formatting"></a> |
| Numbers and number manipulators</h2> |
| <p>Here are the manipulators for number formatting:</p> |
| <ul> |
| <li><code>as::number</code> -- format number according to local specifications, it takes into account various <code>std::ios_base</code> flags like scientific format and precision. <br/> |
| </li> |
| <li><code>as::percent</code> -- format number as "percent" format. For example: <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__manipulators.html#ga365767c66c9c82fb646458f5eace8534">as::percent</a> << 0.25 <<endl; |
| </pre></div> Would create an output that may look like this: <div class="fragment"><pre class="fragment"> |
| 25% |
| </pre></div> <br/> |
| </li> |
| <li><code>as::spellout</code> -- 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/> |
| </li> |
| <li><code>as::ordinal</code> -- 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> |
| </ul> |
| <h2><a class="anchor" id="currency_formatting"></a> |
| Currency formatting</h2> |
| <p>These are the manipulators for currency formatting:</p> |
| <ul> |
| <li><code>as::currency</code> -- set the format to currency mode.</li> |
| <li><code>as::currency_iso</code> -- change the currency format to international, like "USD" instead of "$". This flag is supported when using ICU 4.2 and above.</li> |
| <li><code>as::currency_national</code> -- change currency format to national, like "$".</li> |
| <li><code>as::currency_default</code> -- return to the default (national) currency format.</li> |
| </ul> |
| <dl class="note"><dt><b>Note:</b></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> |
| <h2><a class="anchor" id="date_and_time_formatting"></a> |
| Date and Time formatting</h2> |
| <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> |
| <p>There are four major manipulators for Date and Time formatting:</p> |
| <ul> |
| <li><code>as::date</code> -- date only</li> |
| <li><code>as::time</code> -- time only</li> |
| <li><code>as::datetime</code> -- both date and time</li> |
| <li><code>as::ftime</code> -- 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> |
| </ul> |
| <p>For example:</p> |
| <div class="fragment"><pre class="fragment"> time_t now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0); |
| cout << <span class="stringliteral">"Today is "</span><< <a class="code" href="group__manipulators.html#gae05b82e6658dc573521518fed5f5c77f">as::date</a> << now << <span class="stringliteral">" and tomorrow is "</span> << now+24*3600 << endl; |
| cout << <span class="stringliteral">"Current time is "</span><< <a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">as::time</a> << now << endl; |
| cout << <span class="stringliteral">"The current weekday is "</span><< <a class="code" href="group__manipulators.html#ga84cc8985e5305ef54394e84c10223866">as::ftime</a>(<span class="stringliteral">"%A"</span>) << now << endl; |
| </pre></div><p>More fine-grained control of date-time formatting is also available:</p> |
| <ul> |
| <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> -- change time formatting.</li> |
| <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> -- change date formatting.</li> |
| </ul> |
| <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> |
| <p>By default, the date and time are shown in the local time zone. This behavior may be changed with the following manipulators:</p> |
| <ul> |
| <li><code>as::gmt</code> -- display date and time in GMT.</li> |
| <li><code>as::local_time</code> -- display in local time zone (default).</li> |
| <li><code>as::time_zone</code> -- 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> |
| </ul> |
| <p>For example:</p> |
| <div class="fragment"><pre class="fragment"> <span class="keywordtype">double</span> now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0); |
| cout << <a class="code" href="group__manipulators.html#ga820edf843e20847a0c4ccb8da0c4acd8">as::datetime</a> << <a class="code" href="group__manipulators.html#gac6cb5458543daf651cd6b48812891541">as::local_time</a> << <span class="stringliteral">"Local time is: "</span><< now << endl; |
| cout << <a class="code" href="group__manipulators.html#gac90c969d876305b8584def8632ae1808">as::gmt</a> << <span class="stringliteral">"GMT Time is: "</span><< now <<endl; |
| cout << <a class="code" href="group__manipulators.html#gad51fbdc634fe0c81e5183915e9eeb238">as::time_zone</a>(<span class="stringliteral">"EST"</span>) << <span class="stringliteral">"Eastern Standard Time is: "</span><< now <<endl; |
| </pre></div><p>There is a list of supported <code>strftime</code> flags by ICU backend:</p> |
| <ul> |
| <li><code>%a</code> -- Abbreviated weekday (Sun.)</li> |
| <li><code>%A</code> -- Full weekday (Sunday)</li> |
| <li><code>%b</code> -- Abbreviated month (Jan.)</li> |
| <li><code>%B</code> -- Full month (January)</li> |
| <li><code>%c</code> -- Locale date-time format. <b>Note:</b> prefer using <code>as::datetime</code> </li> |
| <li><code>%d</code> -- Day of Month [01,31]</li> |
| <li><code>%e</code> -- Day of Month [1,31]</li> |
| <li><code>%h</code> -- Same as <code>%b</code> </li> |
| <li><code>%H</code> -- 24 clock hour [00,23]</li> |
| <li><code>%I</code> -- 12 clock hour [01,12]</li> |
| <li><code>%j</code> -- Day of year [1,366]</li> |
| <li><code>%m</code> -- Month [01,12]</li> |
| <li><code>%M</code> -- Minute [00,59]</li> |
| <li><code>%n</code> -- New Line</li> |
| <li><code>%p</code> -- AM/PM in locale representation</li> |
| <li><code>%r</code> -- Time with AM/PM, same as <code>%I:%M:%S</code> %p</li> |
| <li><code>%R</code> -- Same as <code>%H:%M</code> </li> |
| <li><code>%S</code> -- Second [00,61]</li> |
| <li><code>%t</code> -- Tab character</li> |
| <li><code>%T</code> -- Same as <code>%H:%M:%S</code> </li> |
| <li><code>%x</code> -- Local date representation. **Note:** prefer using <code>as::date</code> </li> |
| <li><code>%X</code> -- Local time representation. **Note:** prefer using <code>as::time</code> </li> |
| <li><code>%y</code> -- Year [00,99]</li> |
| <li><code>%Y</code> -- 4 digits year. (2009)</li> |
| <li><code>%Z</code> -- Time Zone</li> |
| <li><code>%%</code> -- Percent symbol</li> |
| </ul> |
| <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> |
| <p><b>General</b> <b>recommendations</b> </p> |
| <ul> |
| <li>Prefer using generic date-time manipulators rather than specifying the full format using <code>as::ftime</code>.</li> |
| <li>Remember that current calendars may be not Gregorian.</li> |
| </ul> |
| <h2><a class="anchor" id="formatting_internals"></a> |
| Internals</h2> |
| <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> |
| <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> |
| </div></div><!-- contents --> |
| </div> |
| <div id="nav-path" class="navpath"> |
| <ul> |
| <li class="navelem"><a class="el" href="index.html">Boost.Locale</a> </li> |
| <li class="navelem"><a class="el" href="using_boost_locale.html">Using Boost.Locale</a> </li> |
| |
| <li class="footer"> |
| © 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. |
| </li> |
| </ul> |
| </div> |
| |
| |
| </body> |
| </html> |
