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: Locale Generation</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('locale_gen.html','');}); 61</script> 62<div id="doc-content"> 63<div class="header"> 64 <div class="headertitle"> 65<div class="title">Locale Generation </div> </div> 66</div><!--header--> 67<div class="contents"> 68<div class="textblock"><p>Each locale is defined by a specific locale identifier, which contains a mandatory part (Language) and several optional parts (Country, Variant, keywords and character encoding of <code>std::string</code>). Boost.Locale uses the POSIX naming convention for locales, i.e. a locale is defined as <code>language[_COUNTRY][.encoding][@variant]</code>, where lang is ISO-639 language name like "en" or "ru", COUNTRY is the ISO-3166 country identifier like "US" or "DE", encoding is the eight-bit character encoding like <code>UTF-8</code> or <code>ISO-8859-1</code>, and variant is additional options for specializing the locale, like <code>euro</code> or <code>calendar=hebrew</code>, see <a class="el" href="locale_gen.html#locale_gen_variant">Variant</a>.</p> 69<p>Note that each locale should include the encoding in order to handle <code>char</code> based strings correctly.</p> 70<h1><a class="anchor" id="locale_gen_basics"></a> 71Basics</h1> 72<p>The class <a class="el" href="classboost_1_1locale_1_1generator.html">generator</a> provides tools to generate the locales we need. The simplest way to use <code>generator</code> is to create a locale and set it as the global one:</p> 73<div class="fragment"><div class="line"><span class="preprocessor">#include <boost/locale.hpp></span></div> 74<div class="line"></div> 75<div class="line"><span class="keyword">using namespace </span>boost::locale;</div> 76<div class="line"><span class="keywordtype">int</span> main()</div> 77<div class="line">{</div> 78<div class="line"> <a class="code" href="classboost_1_1locale_1_1generator.html">generator</a> gen;</div> 79<div class="line"> <span class="comment">// Create locale generator </span></div> 80<div class="line"> std::locale::global(gen(<span class="stringliteral">""</span>)); </div> 81<div class="line"> <span class="comment">// "" - the system default locale, set</span></div> 82<div class="line"> <span class="comment">// it globally</span></div> 83<div class="line">}</div> 84</div><!-- fragment --><p>Of course we can also specify the locale manually</p> 85<div class="fragment"><div class="line">std::locale loc = gen(<span class="stringliteral">"en_US.UTF-8"</span>); </div> 86<div class="line"><span class="comment">// Use English, United States locale</span></div> 87</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd></dd></dl> 88<ul> 89<li>Even if your application uses wide strings everywhere, you should specify the 8-bit encoding to use for 8-bit stream IO operations like <code>cout</code> or <code>fstream</code>. <br/> 90</li> 91<li>The default locale is defined by the environment variables <code>LC_CTYPE</code> , <code>LC_ALL</code> , and <code>LANG</code> in that order (i.e. <code>LC_CTYPE</code> first and <code>LANG</code> last). On Windows, the library also queries the <code>LOCALE_USER_DEFAULT</code> option in the Win32 API when these variables are not set.</li> 92</ul> 93<p><b>Tip:</b> Prefer using UTF-8 Unicode encoding over 8-bit encodings like the ISO-8859-X ones.</p> 94<p>By default the generated locales include all supported categories and character types. However, if your application uses only 8-bit encodings, only wide-character encodings, or only specific facets, you can limit the facet generation to specific categories and character types by calling the <a class="el" href="classboost_1_1locale_1_1generator.html#ae3c095f074329954eb90bb80488c7f76">categories</a> and <a class="el" href="classboost_1_1locale_1_1generator.html#ad5e01c555aa43b438f688dbc29725ab8">characters</a> member functions of the <a class="el" href="classboost_1_1locale_1_1generator.html">generator</a> class.</p> 95<p>For example:</p> 96<div class="fragment"><div class="line">generator gen;</div> 97<div class="line">gen.<a class="code" href="classboost_1_1locale_1_1generator.html#ad5e01c555aa43b438f688dbc29725ab8">characters</a>(wchar_t_facet);</div> 98<div class="line">gen.categories(collation_facet | formatting_facet);</div> 99<div class="line">std::locale::global(gen(<span class="stringliteral">"de_DE.UTF-8"</span>));</div> 100</div><!-- fragment --><h1><a class="anchor" id="locale_gen_variant"></a> 101Variant</h1> 102<p>The variant part of the locale (the part that comes after @ symbol) is localization <a class="el" href="using_localization_backends.html">back-end</a> dependent.</p> 103<h2><a class="anchor" id="locale_gen_variant_non_icu"></a> 104Non ICU Backends</h2> 105<p><a class="el" href="using_localization_backends.html#posix_backend">POSIX</a> and <a class="el" href="using_localization_backends.html#std_backend">std</a> back-ends use their own OS specific naming conventions and depend on the current OS configuration. For example typical Linux distribution provides <code>euro</code> for currency selection, <code>cyrillic</code> and <code>latin</code> for specification of language script.</p> 106<p><a class="el" href="using_localization_backends.html#winapi_backend">winapi</a> back-end does not support any variants.</p> 107<h2><a class="anchor" id="locale_gen_variant_icu"></a> 108ICU Backend</h2> 109<p>ICU provides wide range of locale variant options. For detailed instructions read <a href="http://userguide.icu-project.org/locale">this</a> ICU manual pages.</p> 110<p>However in general it is represented as set of key=value pairs separated with a semicolon ";" For example: "@collation=phonebook;calendar=islamic-civil".</p> 111<p>Currently ICU supports following keys:</p> 112<ul> 113<li><code>calendar</code> - the calendar used for the current locale. For example: <code>gregorian</code>, <code>japanese</code>, <code>buddhist</code>, <code>islamic</code>, <code>hebrew</code>, <code>chinese</code>, <code>islamic-civil</code>.</li> 114<li><code>collation</code> - the collation order used for this locales, for example <code>phonebook</code>, <code>pinyin</code>, <code>traditional</code>, <code>stroke</code>, <code>direct</code>, <code>posix</code>.</li> 115<li><code>currency</code> - the currency used in this locale, the standard 3 letter code like USD or JPY.</li> 116<li><code>numbers</code> - the numbering system used, for example: <code>latn</code>, <code>arab</code>, <code>thai</code>.</li> 117</ul> 118<p>Please refer to CLDR and ICU documentation for exact list of keys and values:</p> 119<ul> 120<li><a href="http://userguide.icu-project.org/locale#TOC-Keywords">ICU User Guide/Locale/Keywords</a></li> 121<li><a href="http://www.unicode.org/reports/tr35/">Unicode Locale Data Markup Language</a> </li> 122</ul> 123</div></div><!-- contents --> 124</div><!-- doc-content --> 125 126 <li class="footer"> 127© 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. 128 </li> 129 </ul> 130 </div> 131</body> 132</html> 133
