ceph/src/boost/libs/locale/doc/html/using_localization_backends.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 <meta name="generator" content="Doxygen 1.8.6"/>
   7 <title>Boost.Locale: Using Localization Backends</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&#160;Page</span></a></li>
  40       <li class="current"><a href="pages.html"><span>Related&#160;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('using_localization_backends.html','');});
  61 </script>
  62 <div id="doc-content">
  63 <div class="header">
  64   <div class="headertitle">
  65 <div class="title">Using Localization Backends </div>  </div>
  66 </div><!--header-->
  67 <div class="contents">
  68 <div class="textblock"><p>By default, Boost.Locale uses ICU for all localization and text manipulation tasks. This is the most powerful library available, but sometimes we don't need the full power of this library or we want to reduce dependencies from third-party libraries, and ICU is by no means a small library.</p>
  69 <p>Boost.Locale provides an option to use non-ICU based localization backends. Although usually less powerful, these often provide all you need: message formatting, currency, date, time, number formatting, basic collation and case manipulation. They are implemented using the standard OS API or a C or C++ library.</p>
  70 <h1><a class="anchor" id="when_to_use_non_icu_backends"></a>
  71 When to use non-ICU backends</h1>
  72 <p>There are situations when using non-ICU based localization is appropriate:</p>
  73 <ul>
  74 <li>Embedded systems, where the ICU library is very hefty.</li>
  75 <li>Applications where only basic features like message, date, and time formatting and basic collation are required, and using a third-party library like ICU would be too complicated.</li>
  76 <li>Performance. ICU is a very powerful library, but it is generally slower than the standard library. Sometimes it's better to use a simpler but faster localization backend.</li>
  77 </ul>
  78 <h1><a class="anchor" id="non_icu_backends"></a>
  79 Non-ICU Backends</h1>
  80 <p>All of the alternate backends have these limitations:</p>
  81 <ul>
  82 <li>Only the Gregorian calendar is supported and it is based on capabilites of mktime functionality (including dates range)</li>
  83 <li>No boundary analysis.</li>
  84 <li>Case handling is very simple and based on single codepoint conversions, though they still handle UTF-8 better than the standard library.</li>
  85 <li>Time zone specification is very limited: either local time or a time zone in the format "GMT+HH:MM".</li>
  86 <li>No percent formatting, no spellout or ordinal number formatting.</li>
  87 <li>Collation, with exception of the <code>winapi</code> backend, is limited to a single level, similar to what is done by <code>strcoll</code>.</li>
  88 </ul>
  89 <h2><a class="anchor" id="std_backend"></a>
  90 std - The standard C++ library backend</h2>
  91 <p>This localization backend is based on the standard C++ library.</p>
  92 <p>It is supported on all platforms, but is only actually useful on platforms where the standard library supports locales besides "C" and "POSIX": on Linux with GCC or Intel compilers, and under the MSVC compiler.</p>
  93 <p>It works around some common standard library bugs like invalid UTF-8 generation for numeric formatting, and it gives otherwise-absent POSIX locales names and UTF-8 support under MSVC.</p>
  94 <p>It is very useful when the compiler and the library actually give fine localization support, like GCC under Linux or MSVC under Windows.</p>
  95 <h2><a class="anchor" id="posix_backend"></a>
  96 posix - POSIX 2008 C library</h2>
  97 <p>This backend is based on the latest POSIX 2008 standards, and uses POSIX api functions like <code>newlocale</code>, <code>freelocale</code>, <code>strftime_l</code> etc. It is available on the Linux and Mac OS X platforms.</p>
  98 <p>It gives you simple and ready-made localization support, most notably under Mac OS X where GCC's <code>libstdc++</code> does not support locales.</p>
  99 <dl class="section note"><dt>Note</dt><dd>The POSIX backend only supports UTF-8, single-byte, and double-byte encodings.</dd></dl>
 100 <h2><a class="anchor" id="winapi_backend"></a>
 101 winapi - Win32 API.</h2>
 102 <p>The Win32API-based localization backend provides decent UTF-8/UTF-16 locale support. It is based on Windows API functions like <code>GetLocaleInfoW</code>, <code>LCMapStringW</code>, <code>GetDateFormatW</code> etc and provides good localization support even on the MinGW and Cygwin platforms, which normally have problems with this.</p>
 103 <dl class="section note"><dt>Note</dt><dd></dd></dl>
 104 <ul>
 105 <li>If you using GCC compiler under Windows you need GCC-4.x series to use it, GCC-3.4 is not supported</li>
 106 <li>Only UTF-8 as narrow locale encoding and UTF-16 as wide encoding are supported.</li>
 107 </ul>
 108 <h1><a class="anchor" id="supported_features_by_backends"></a>
 109 Supported Features</h1>
 110 <table  border="1" sellpadding="5" sellspacing="3">
 111 <tr>
 112 <th>Backend </th><th>icu</th><th>posix</th><th>winapi</th><th>std  </th></tr>
 113 <tr>
 114 <th>Message Formatting </th><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes  </td></tr>
 115 <tr>
 116 <th>Non UTF-8 encodings </th><td>Yes</td><td>Yes</td><td>No</td><td>Yes  </td></tr>
 117 <tr>
 118 <th>Date/Time Formatting/Parsing </th><td>Yes</td><td>Formatting Only</td><td>Formatting Only</td><td>Formatting Only  </td></tr>
 119 <tr>
 120 <th>Monetary Formatting/Parsing </th><td>Yes</td><td>Formatting Only</td><td>Formatting Only</td><td>Yes  </td></tr>
 121 <tr>
 122 <th>Number Formatting/Parsing </th><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes  </td></tr>
 123 <tr>
 124 <th>Numbers as Percent, Spelled Out </th><td>Yes</td><td>No</td><td>No</td><td>No  </td></tr>
 125 <tr>
 126 <th>Case Manipulation </th><td>Yes</td><td>Basic</td><td>Basic</td><td>Basic  </td></tr>
 127 <tr>
 128 <th>Collation </th><td>Full</td><td>Linux - 1 level<br/>
 129 Mac OS X - broken</td><td>3 levels</td><td>1 level  </td></tr>
 130 <tr>
 131 <th>Calendar </th><td>Yes</td><td>Gregorian Only</td><td>Gregorian Only</td><td>Gregorian Only  </td></tr>
 132 <tr>
 133 <th>Boundary Analysis </th><td>Yes</td><td>No</td><td>No</td><td>No  </td></tr>
 134 <tr>
 135 <th>Unicode Normalization </th><td>Yes</td><td>No</td><td>Vista and above</td><td>No  </td></tr>
 136 <tr>
 137 <th>C++0x characters </th><td>Yes</td><td>No</td><td>No</td><td>Yes  </td></tr>
 138 <tr>
 139 <th>OS Support </th><td>Any</td><td>Linux, Mac OS X</td><td>Windows, Cygwin</td><td>Any  </td></tr>
 140 <tr>
 141 <th>Useful on </th><td>Any Platform</td><td>Linux and Mac OS X</td><td>Windows/MinGW/Cygwin</td><td>Linux with GCC or Intel<br/>
 142 Windows with MSVC  </td></tr>
 143 </table>
 144 <h1><a class="anchor" id="using_localization_backends"></a>
 145 Using Localization Backends</h1>
 146 <p>Accessing a localization backend is done via the <a class="el" href="classboost_1_1locale_1_1localization__backend__manager.html" title="Localization backend manager is a class that holds various backend and allows creation of their combi...">boost::locale::localization_backend_manager</a> class.</p>
 147 <p>You can create your own <a class="el" href="classboost_1_1locale_1_1localization__backend__manager.html" title="Localization backend manager is a class that holds various backend and allows creation of their combi...">boost::locale::localization_backend_manager</a> by starting with a global backend via the <a class="el" href="classboost_1_1locale_1_1localization__backend__manager.html#a65649bc161a0cc160da9b40a9ad14e20">boost::locale::localization_backend_manager::global</a> static member function and modifying it.</p>
 148 <p>For example:</p>
 149 <div class="fragment"><div class="line">localization_backend_manager my = localization_backend_manager::global(); </div>
 150 <div class="line"><span class="comment">// Get global backend</span></div>
 151 <div class="line"></div>
 152 <div class="line">my.select(<span class="stringliteral">&quot;std&quot;</span>); </div>
 153 <div class="line"><span class="comment">// select std backend as default</span></div>
 154 <div class="line"></div>
 155 <div class="line">generator gen(my); </div>
 156 <div class="line"><span class="comment">// create a generator that uses this backend.</span></div>
 157 <div class="line"></div>
 158 <div class="line">localization_backend_manager::global(my);</div>
 159 <div class="line"><span class="comment">// set this backend globally</span></div>
 160 <div class="line"></div>
 161 <div class="line">generator gen2();</div>
 162 <div class="line"><span class="comment">// now this one would use the new global backend.</span></div>
 163 </div><!-- fragment --><p>You can also create a mixture of several backends, using for example <code>icu</code> for one kind of operation and <code>std</code> for all others:</p>
 164 <div class="fragment"><div class="line">localization_backend_manager my = localization_backend_manager::global(); </div>
 165 <div class="line"><span class="comment">// Get global backend</span></div>
 166 <div class="line"></div>
 167 <div class="line">my.select(<span class="stringliteral">&quot;std&quot;</span>); </div>
 168 <div class="line"><span class="comment">// select std backend as default for all categories</span></div>
 169 <div class="line">my.select(<span class="stringliteral">&quot;icu&quot;</span>,boundary_facet); </div>
 170 <div class="line"><span class="comment">// select icu backend for boundary analysis (since it is not supported by \c std)</span></div>
 171 </div><!-- fragment --> </div></div><!-- contents -->
 172 </div><!-- doc-content -->
 173
 174     <li class="footer">
 175 &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.
 176     </li>
 177    </ul>
 178  </div>
 179 </body>
 180 </html>