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 Page</span></a></li> 40 <li class="current"><a href="pages.html"><span>Related 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 << <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> << 123.45 << endl;</div> 71<div class="line"><span class="comment">// display 123.45 in local currency representation.</span></div> 72<div class="line">cin >> <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> >> 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> 76Numbers and number manipulators</h1> 77<p>Here are the manipulators for number formatting:</p> 78<ul> 79<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/> 80</li> 81<li><code>as::percent</code> – format number as "percent" format. For example: <div class="fragment"><div class="line">cout << <a class="code" href="group__manipulators.html#ga365767c66c9c82fb646458f5eace8534">as::percent</a> << 0.25 <<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> – 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> – 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> 89Currency formatting</h1> 90<p>These are the manipulators for currency formatting:</p> 91<ul> 92<li><code>as::currency</code> – set the format to currency mode.</li> 93<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> 94<li><code>as::currency_national</code> – change currency format to national, like "$".</li> 95<li><code>as::currency_default</code> – 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> 99Date 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> – date only</li> 104<li><code>as::time</code> – time only</li> 105<li><code>as::datetime</code> – both date and time</li> 106<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> 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 << <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;</div> 111<div class="line">cout << <span class="stringliteral">"Current time is "</span><< <a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">as::time</a> << now << endl;</div> 112<div class="line">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;</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> – 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> – 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> – display date and time in GMT.</li> 122<li><code>as::local_time</code> – display in local time zone (default).</li> 123<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> 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 << <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;</div> 128<div class="line">cout << <a class="code" href="group__manipulators.html#gac90c969d876305b8584def8632ae1808">as::gmt</a> << <span class="stringliteral">"GMT Time is: "</span><< now <<endl;</div> 129<div class="line">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;</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> – Abbreviated weekday (Sun.)</li> 133<li><code>%A</code> – Full weekday (Sunday)</li> 134<li><code>%b</code> – Abbreviated month (Jan.)</li> 135<li><code>%B</code> – Full month (January)</li> 136<li><code>%c</code> – Locale date-time format. <b>Note:</b> prefer using <code>as::datetime</code> </li> 137<li><code>%d</code> – Day of Month [01,31]</li> 138<li><code>%e</code> – Day of Month [1,31]</li> 139<li><code>%h</code> – Same as <code>%b</code> </li> 140<li><code>%H</code> – 24 clock hour [00,23]</li> 141<li><code>%I</code> – 12 clock hour [01,12]</li> 142<li><code>%j</code> – Day of year [1,366]</li> 143<li><code>%m</code> – Month [01,12]</li> 144<li><code>%M</code> – Minute [00,59]</li> 145<li><code>%n</code> – New Line</li> 146<li><code>%p</code> – AM/PM in locale representation</li> 147<li><code>%r</code> – Time with AM/PM, same as <code>%I:%M:%S</code> %p</li> 148<li><code>%R</code> – Same as <code>%H:%M</code> </li> 149<li><code>%S</code> – Second [00,61]</li> 150<li><code>%t</code> – Tab character</li> 151<li><code>%T</code> – Same as <code>%H:%M:%S</code> </li> 152<li><code>%x</code> – Local date representation. <b>Note:</b> prefer using <code>as::date</code> </li> 153<li><code>%X</code> – Local time representation. <b>Note:</b> prefer using <code>as::time</code> </li> 154<li><code>%y</code> – Year [00,99]</li> 155<li><code>%Y</code> – 4 digits year. (2009)</li> 156<li><code>%Z</code> – Time Zone</li> 157<li><code>%%</code> – 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> 166Internals</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© 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> 179
