179 lines
13 KiB
HTML
179 lines
13 KiB
HTML
<!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 Page</span></a></li>
|
|
<li class="current"><a href="pages.html"><span>Related 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 << <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> << 123.45 << endl;</div>
|
|
<div class="line"><span class="comment">// display 123.45 in local currency representation.</span></div>
|
|
<div class="line">cin >> <a class="code" href="group__manipulators.html#ga97c4997f9692834ea7b5ed3e8137d5fd">as::currency</a> >> 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> – 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"><div class="line">cout << <a class="code" href="group__manipulators.html#ga365767c66c9c82fb646458f5eace8534">as::percent</a> << 0.25 <<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> – 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>
|
|
<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> – 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="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> – 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"><div class="line">time_t now=<a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0);</div>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
</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> – 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"><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 << <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>
|
|
<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>
|
|
<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>
|
|
</div><!-- fragment --><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. <b>Note:</b> prefer using <code>as::date</code> </li>
|
|
<li><code>%X</code> – Local time representation. <b>Note:</b> 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>
|
|
<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">
|
|
© 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>
|