libs/locale/doc/html/locale_gen.html

   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 <title>Boost.Locale: Locale Generation</title>
   7
   8 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  10 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  11 <script type="text/javascript" src="jquery.js"></script>
  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 </script>
  17
  18
  19 </head>
  20 <body>
  21 <div id="top"><!-- do not remove this div! -->
  22
  23
  24 <div id="titlearea">
  25 <table cellspacing="0" cellpadding="0">
  26  <tbody>
  27  <tr style="height: 56px;">
  28
  29   <td id="projectlogo"><img alt="Logo" src="boost-small.png"/></td>
  30
  31
  32   <td style="padding-left: 0.5em;">
  33    <div id="projectname">Boost.Locale
  34
  35    </div>
  36
  37   </td>
  38
  39
  40
  41  </tr>
  42  </tbody>
  43 </table>
  44 </div>
  45
  46 <!-- Generated by Doxygen 1.7.6.1 -->
  47   <div id="navrow1" class="tabs">
  48     <ul class="tablist">
  49       <li><a href="index.html"><span>Main&#160;Page</span></a></li>
  50       <li><a href="modules.html"><span>Modules</span></a></li>
  51       <li><a href="namespaces.html"><span>Namespaces</span></a></li>
  52       <li><a href="annotated.html"><span>Classes</span></a></li>
  53       <li><a href="files.html"><span>Files</span></a></li>
  54       <li><a href="examples.html"><span>Examples</span></a></li>
  55     </ul>
  56   </div>
  57 </div>
  58 <div id="side-nav" class="ui-resizable side-nav-resizable">
  59   <div id="nav-tree">
  60     <div id="nav-tree-contents">
  61     </div>
  62   </div>
  63   <div id="splitbar" style="-moz-user-select:none;"
  64        class="ui-resizable-handle">
  65   </div>
  66 </div>
  67 <script type="text/javascript">
  68   initNavTree('locale_gen.html','');
  69 </script>
  70 <div id="doc-content">
  71 <div class="header">
  72   <div class="headertitle">
  73 <div class="title">Locale Generation </div>  </div>
  74 </div><!--header-->
  75 <div class="contents">
  76 <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>
  77 <p>Note that each locale should include the encoding in order to handle <code>char</code> based strings correctly.</p>
  78 <h2><a class="anchor" id="locale_gen_basics"></a>
  79 Basics</h2>
  80 <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>
  81 <div class="fragment"><pre class="fragment"><span class="preprocessor">    #include &lt;boost/locale.hpp&gt;</span>
  82
  83     <span class="keyword">using namespace </span>boost::locale;
  84     <span class="keywordtype">int</span> main()
  85     {
  86         <a class="code" href="classboost_1_1locale_1_1generator.html" title="the major class used for locale generation">generator</a> gen;
  87         <span class="comment">// Create locale generator </span>
  88         std::locale::global(gen(<span class="stringliteral">&quot;&quot;</span>));
  89         <span class="comment">// &quot;&quot; - the system default locale, set</span>
  90         <span class="comment">// it globally</span>
  91     }
  92 </pre></div><p>Of course we can also specify the locale manually</p>
  93 <div class="fragment"><pre class="fragment">    std::locale loc = gen(<span class="stringliteral">&quot;en_US.UTF-8&quot;</span>);
  94     <span class="comment">// Use English, United States locale</span>
  95 </pre></div><dl class="note"><dt><b>Note:</b></dt><dd></dd></dl>
  96 <ul>
  97 <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/>
  98 </li>
  99 <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>
 100 </ul>
 101 <p><b>Tip:</b> Prefer using UTF-8 Unicode encoding over 8-bit encodings like the ISO-8859-X ones.</p>
 102 <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>
 103 <p>For example:</p>
 104 <div class="fragment"><pre class="fragment">    generator gen;
 105     gen.<a class="code" href="classboost_1_1locale_1_1generator.html#ad5e01c555aa43b438f688dbc29725ab8">characters</a>(wchar_t_facet);
 106     gen.categories(collation_facet | formatting_facet);
 107     std::locale::global(gen(<span class="stringliteral">&quot;de_DE.UTF-8&quot;</span>));
 108 </pre></div><h2><a class="anchor" id="locale_gen_variant"></a>
 109 Variant</h2>
 110 <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>
 111 <h3><a class="anchor" id="locale_gen_variant_non_icu"></a>
 112 Non ICU Backends</h3>
 113 <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>
 114 <p><a class="el" href="using_localization_backends.html#winapi_backend">winapi</a> back-end does not support any variants.</p>
 115 <h3><a class="anchor" id="locale_gen_variant_icu"></a>
 116 ICU Backend</h3>
 117 <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>
 118 <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>
 119 <p>Currently ICU supports following keys:</p>
 120 <ul>
 121 <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>
 122 <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>
 123 <li><code>currency</code> - the currency used in this locale, the standard 3 letter code like USD or JPY.</li>
 124 <li><code>numbers</code> - the numbering system used, for example: <code>latn</code>, <code>arab</code>, <code>thai</code>.</li>
 125 </ul>
 126 <p>Please refer to CLDR and ICU documentation for exact list of keys and values:</p>
 127 <ul>
 128 <li><a href="http://userguide.icu-project.org/locale#TOC-Keywords">ICU User Guide/Locale/Keywords</a></li>
 129 <li><a href="http://www.unicode.org/reports/tr35/">Unicode Locale Data Markup Language</a> </li>
 130 </ul>
 131 </div></div><!-- contents -->
 132 </div>
 133   <div id="nav-path" class="navpath">
 134     <ul>
 135       <li class="navelem"><a class="el" href="index.html">Boost.Locale</a>      </li>
 136       <li class="navelem"><a class="el" href="using_boost_locale.html">Using Boost.Locale</a>      </li>
 137
 138     <li class="footer">
 139 &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.
 140     </li>
 141    </ul>
 142  </div>
 143
 144
 145 </body>
 146 </html>