<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: Localized Text Formatting</title>
+
<link href="tabs.css" rel="stylesheet" type="text/css"/>
-<link href="doxygen.css" rel="stylesheet" type="text/css"/>
-<link rel="stylesheet" type="text/css" href="../style/section-basic.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="boost-common-heading-doc">
- <div class="heading-inner">
- <div class="heading-placard"></div>
-
- <h1 class="heading-title">
- <a href="http://www.boost.org/">
- <img src="../style/space.png" alt= "Boost C++ Libraries" class="heading-logo" />
- <span class="heading-boost">Boost</span>
- <span class="heading-cpplibraries">C++ Libraries</span>
- </a>
- </h1>
+<div id="top"><!-- do not remove this div! -->
- <p class="heading-quote">
- <q>...one of the most highly
- regarded and expertly designed C++ library projects in the
- world.</q>
-
- <span class="heading-attribution">— <a href=
- "http://www.gotw.ca/" class="external">Herb Sutter</a> and <a href=
- "http://en.wikipedia.org/wiki/Andrei_Alexandrescu" class="external">Andrei
- Alexandrescu</a>, <a href=
- "http://safari.awprofessional.com/?XmlId=0321113586" class="external">C++
- Coding Standards</a></span>
- </p>
- </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>
-<div id="boost-common-heading-doc-spacer"></div>
-<!-- Generated by Doxygen 1.7.1 -->
-<div class="navigation" id="top">
- <div class="tabs">
+<!-- Generated by Doxygen 1.7.6.1 -->
+ <div id="navrow1" class="tabs">
<ul class="tablist">
- <li><a href="main.html"><span>Main Page</span></a></li>
+ <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="examples.html"><span>Examples</span></a></li>
</ul>
</div>
- <div class="navpath">
- <ul>
- <li><a class="el" href="main.html">Boost.Locale</a> </li>
- <li><a class="el" href="using_boost_locale.html">Using Boost.Locale</a> </li>
- </ul>
+</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('localized_text_formatting.html','');
+</script>
+<div id="doc-content">
<div class="header">
<div class="headertitle">
-<h1>Localized Text Formatting </h1> </div>
-</div>
+<div class="title">Localized Text Formatting </div> </div>
+</div><!--header-->
<div class="contents">
-<p>The <code>iostream</code> manipulators are very useful, but when we create a messages for the user, sometimes we need something like good old <code>printf</code> or <code>boost::format</code>.</p>
+<div class="textblock"><p>The <code>iostream</code> manipulators are very useful, but when we create a messages for the user, sometimes we need something like good old <code>printf</code> or <code>boost::format</code>.</p>
<p>Unfortunately <code>boost::format</code> has several limitations in context of localization:</p>
<ol type="1">
<li>It renders all parameters using global locale rather than target <code>ostream</code> locale. For example: <br/>
<li>It knows nothing about the new Boost.Locale manipulators.</li>
<li>The <code>printf-like</code> syntax is very limited for formatting complex localized data, not allowing the formatting of dates, times, or currencies</li>
</ol>
-<p>Thus a new class, boost::locale::format, was introduced. For example:</p>
+<p>Thus a new class, <a class="el" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">boost::locale::format</a>, was introduced. For example:</p>
<div class="fragment"><pre class="fragment"> wcout << <a class="code" href="group__format.html#ga610f3ae827801febc962019cf82a2227">wformat</a>(L<span class="stringliteral">"Today {1,date} I would meet {2} at home"</span>) % <a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>(0) % name <<endl;
</pre></div><p>Each format specifier is enclosed within <code>{}</code> brackets, is separated with a comma "," and may have an additional option after an equals symbol '='. This option may be simple ASCII text or single-quoted localized text. If a single-quote should be inserted within the text, it may be represented with a pair of single-quote characters.</p>
<p>Here is an example of a format string:</p>
local-string : quoted-text | quoted-text local-string;
quoted-text : '[^']*' ;
</pre></div><p>You can include literal '{' and '}' by inserting double "{{" or "}}" to the text.</p>
-<div class="fragment"><pre class="fragment">cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<a class="code" href="group__message.html#ga7f35933e136f9202baa66128d87e5d43" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Unexpected `{{' in line {1} in file {2}"</span>)) % pos % file;
+<div class="fragment"><pre class="fragment">cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<a class="code" href="group__message.html#ga58e9599005608845d2b022d499dc97f6" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Unexpected `{{' in line {1} in file {2}"</span>)) % pos % file;
</pre></div><p>Would display something like</p>
<div class="fragment"><pre class="fragment">
Unexpected `{' in line 5 in file source.cpp
<li><code>width</code> or <code>w</code> -- set field width (requires parameter).</li>
<li><code>precision</code> or <code>p</code> -- set precision (requires parameter).</li>
<li><code>locale</code> -- with parameter -- switch locales for the current operation. This command generates a locale with formatting facets, giving more fine grained control of formatting. For example: <br/>
- <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"This article was published at {1,date=l} (Gregorian) {1,locale=he_IL@calendar=hebrew,date=l} (Hebrew)"</span>) % date;
+ <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"This article was published at {1,date=l} (Gregorian) {1,locale=he_IL@calendar=hebrew,date=l} (Hebrew)"</span>) % <a class="code" href="group__manipulators.html#gae05b82e6658dc573521518fed5f5c77f">date</a>;
</pre></div></li>
<li><code>timezone</code> or <code>tz</code> -- the name of the timezone to display the time in. For example:<br/>
- <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"Time is: Local {1,time}, ({1,time,tz=EET} Eastern European Time)"</span>) % date;
+ <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"Time is: Local {1,time}, ({1,time,tz=EET} Eastern European Time)"</span>) % <a class="code" href="group__manipulators.html#gae05b82e6658dc573521518fed5f5c77f">date</a>;
</pre></div></li>
<li><code>local</code> - display the time in local time</li>
-<li><code>gmt</code> - display the time in UTC time scale <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"Local time is: {1,time,local}, universal time is {1,time,gmt}"</span>) % time;
+<li><code>gmt</code> - display the time in UTC time scale <div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"Local time is: {1,time,local}, universal time is {1,time,gmt}"</span>) % <a class="code" href="group__manipulators.html#gae669b101cbeaed6f6d246ebdcaa8f39c">time</a>;
</pre></div></li>
</ul>
<p>The constructor for the <a class="el" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a> class can take an object of type <a class="el" href="group__message.html#ga556e3e7696302902b2242a7a94516dee">message</a>, simplifying integration with message translation code.</p>
<p>For example:</p>
-<div class="fragment"><pre class="fragment"> cout<< <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<a class="code" href="group__message.html#ga7f35933e136f9202baa66128d87e5d43" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b) << endl;
+<div class="fragment"><pre class="fragment"> cout<< <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<a class="code" href="group__message.html#ga58e9599005608845d2b022d499dc97f6" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b) << endl;
</pre></div><p>A formatted string can be fetched directly by using the <a class="el" href="classboost_1_1locale_1_1basic__format.html#a6bc65d7993e3ab6ad51809ef8fb65400">str(std::locale const &loc=std::locale())</a> member function. For example:</p>
-<div class="fragment"><pre class="fragment"> std::wstring de = (<a class="code" href="group__format.html#ga610f3ae827801febc962019cf82a2227">wformat</a>(<a class="code" href="group__message.html#ga7f35933e136f9202baa66128d87e5d43" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b)).str(de_locale);
- std::wstring fr = (<a class="code" href="group__format.html#ga610f3ae827801febc962019cf82a2227">wformat</a>(<a class="code" href="group__message.html#ga7f35933e136f9202baa66128d87e5d43" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b)).str(fr_locale);
-</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>There is one significant difference between <code>boost::format</code> and <code>boost::locale::format</code>: Boost.Locale's format converts its parameters only when written to an <code>ostream</code> or when the `str()` member function is called. It only saves references to the objects that can be written to a stream.</dd></dl>
+<div class="fragment"><pre class="fragment"> std::wstring de = (<a class="code" href="group__format.html#ga610f3ae827801febc962019cf82a2227">wformat</a>(<a class="code" href="group__message.html#ga58e9599005608845d2b022d499dc97f6" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b)).str(de_locale);
+ std::wstring fr = (<a class="code" href="group__format.html#ga610f3ae827801febc962019cf82a2227">wformat</a>(<a class="code" href="group__message.html#ga58e9599005608845d2b022d499dc97f6" title="Translate a message, msg is not copied.">translate</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>)) % a % b % (a+b)).str(fr_locale);
+</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>There is one significant difference between <code>boost::format</code> and <code><a class="el" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">boost::locale::format</a></code>: Boost.Locale's format converts its parameters only when written to an <code>ostream</code> or when the `str()` member function is called. It only saves references to the objects that can be written to a stream.</dd></dl>
<p>This is generally not a problem when all operations are done in one statement, such as:</p>
<div class="fragment"><pre class="fragment"> cout << <a class="code" href="group__format.html#gad7914df7b54382c1ad7f5360676fe2e8">format</a>(<span class="stringliteral">"Adding {1} to {2}, we get {3}"</span>) % a % b % (a+b);
</pre></div><p>Because the temporary value of <code></code>(a+b) exists until the formatted data is actually written to the stream. But following code is wrong:</p>
<span class="keywordtype">int</span> a_plus_b = a+b;
fmt % a_plus_b;
cout << fmt;
-</pre></div> </div>
-<hr class="footer"/><address class="footer"><small>
-© Copyright 2009-2011 Artyom Beilis, Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License</a>, Version 1.0.
-</small></address>
+</pre></div> </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>
projects / platform / upstream / boost.git / blobdiff