<!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"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>Boost.Locale: Numbers, Time and Currency formatting and parsing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<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>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</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><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){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"><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>
<div class="line"><span class="comment">// display 123.45 in local currency representation.</span></div>
<div class="line">cin &gt;&gt; <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> &gt;&gt; x ;</div>
<div class="line"><span class="comment">// Parse currency representation and store it in x</span></div>
</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>
<h1><a class="anchor" id="numbers_formatting"></a>
Numbers and number manipulators</h1>
<p>Here are the manipulators for number formatting:</p>
<ul>
<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/>
</li>
<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>
</div><!-- fragment --> Would create an output that may look like this: <pre class="fragment">    25%</pre> <br/>
</li>
<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/>
</li>
<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>
</ul>
<h1><a class="anchor" id="currency_formatting"></a>
Currency formatting</h1>
<p>These are the manipulators for currency formatting:</p>
<ul>
<li><code>as::currency</code> &ndash; set the format to currency mode.</li>
<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>
<li><code>as::currency_national</code> &ndash; change currency format to national, like "$".</li>
<li><code>as::currency_default</code> &ndash; return to the default (national) currency format.</li>
</ul>
<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>
<h1><a class="anchor" id="date_and_time_formatting"></a>
Date and Time formatting</h1>
<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> &ndash; date only</li>
<li><code>as::time</code> &ndash; time only</li>
<li><code>as::datetime</code> &ndash; both date and time</li>
<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>
</ul>
<p>For example:</p>
<div class="fragment"><div class="line">time_t now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0);</div>
<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>
<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>
<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>
</div><!-- fragment --><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> &ndash; 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> &ndash; 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> &ndash; display date and time in GMT.</li>
<li><code>as::local_time</code> &ndash; display in local time zone (default).</li>
<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>
</ul>
<p>For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">double</span> now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0);</div>
<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>
<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>
<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>
</div><!-- fragment --><p>There is a list of supported <code>strftime</code> flags by ICU backend:</p>
<ul>
<li><code>%a</code> &ndash; Abbreviated weekday (Sun.)</li>
<li><code>%A</code> &ndash; Full weekday (Sunday)</li>
<li><code>%b</code> &ndash; Abbreviated month (Jan.)</li>
<li><code>%B</code> &ndash; Full month (January)</li>
<li><code>%c</code> &ndash; Locale date-time format. <b>Note:</b> prefer using <code>as::datetime</code> </li>
<li><code>%d</code> &ndash; Day of Month [01,31]</li>
<li><code>%e</code> &ndash; Day of Month [1,31]</li>
<li><code>%h</code> &ndash; Same as <code>%b</code> </li>
<li><code>%H</code> &ndash; 24 clock hour [00,23]</li>
<li><code>%I</code> &ndash; 12 clock hour [01,12]</li>
<li><code>%j</code> &ndash; Day of year [1,366]</li>
<li><code>%m</code> &ndash; Month [01,12]</li>
<li><code>%M</code> &ndash; Minute [00,59]</li>
<li><code>%n</code> &ndash; New Line</li>
<li><code>%p</code> &ndash; AM/PM in locale representation</li>
<li><code>%r</code> &ndash; Time with AM/PM, same as <code>%I:%M:%S</code> %p</li>
<li><code>%R</code> &ndash; Same as <code>%H:%M</code> </li>
<li><code>%S</code> &ndash; Second [00,61]</li>
<li><code>%t</code> &ndash; Tab character</li>
<li><code>%T</code> &ndash; Same as <code>%H:%M:%S</code> </li>
<li><code>%x</code> &ndash; Local date representation. <b>Note:</b> prefer using <code>as::date</code> </li>
<li><code>%X</code> &ndash; Local time representation. <b>Note:</b> prefer using <code>as::time</code> </li>
<li><code>%y</code> &ndash; Year [00,99]</li>
<li><code>%Y</code> &ndash; 4 digits year. (2009)</li>
<li><code>%Z</code> &ndash; Time Zone</li>
<li><code>%%</code> &ndash; 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>
<h1><a class="anchor" id="formatting_internals"></a>
Internals</h1>
<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><!-- doc-content -->

    <li class="footer">
&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.
    </li>
   </ul>
 </div>
</body>
</html>
