ceph/src/boost/libs/locale/doc/using_localization_backends.txt

   1 //
   2 //  Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
   3 //
   4 //  Distributed under the Boost Software License, Version 1.0. (See
   5 //  accompanying file LICENSE_1_0.txt or copy at
   6 //  http://www.boost.org/LICENSE_1_0.txt)
   7 //
   8
   9 // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen
  10 /*!
  11 \page using_localization_backends Using Localization Backends
  12
  13 By default, Boost.Locale uses ICU for all localization and text manipulation tasks.
  14 This is the most powerful library available, but sometimes we don't need
  15 the full power of this library or we want to reduce dependencies from third-party
  16 libraries, and ICU is by no means a small library.
  17
  18 Boost.Locale provides an option to use non-ICU based localization
  19 backends. Although usually less powerful, these often provide all you need:
  20 message formatting, currency, date, time, number formatting, basic collation and
  21 case manipulation. They are implemented using the standard OS API or a C or C++ library.
  22
  23 \section when_to_use_non_icu_backends When to use non-ICU backends
  24
  25 There are situations when using non-ICU based localization is appropriate:
  26
  27 - Embedded systems, where the ICU library is very hefty.
  28 - Applications where only basic features like message, date, and time formatting and
  29   basic collation are required, and using a third-party library like ICU would be too
  30   complicated.
  31 - Performance. ICU is a very powerful library, but it is generally slower than the standard
  32   library. Sometimes it's better to use a simpler but faster localization backend.
  33
  34
  35 \section non_icu_backends Non-ICU Backends
  36
  37 All of the alternate backends have these limitations:
  38
  39 - Only the Gregorian calendar is supported and it is based
  40   on capabilites of mktime functionality (including dates range)
  41 - No boundary analysis.
  42 - Case handling is very simple and based on single codepoint conversions,
  43   though they still handle UTF-8 better than the standard library.
  44 - Time zone specification is very limited: either local time or a time zone
  45   in the format "GMT+HH:MM".
  46 - No percent formatting, no spellout or ordinal number formatting.
  47 - Collation, with exception of the \c winapi backend, is limited to a single level,
  48   similar to what is done by \c strcoll.
  49
  50
  51 \subsection std_backend std - The standard C++ library backend
  52
  53 This localization backend is based on the standard C++ library.
  54
  55 It is supported on all platforms, but is only actually useful on platforms where
  56 the standard library supports locales besides "C" and "POSIX": on Linux with GCC
  57 or Intel compilers, and under the MSVC compiler.
  58
  59 It works around some common standard library bugs like invalid UTF-8 generation for numeric
  60 formatting, and it gives otherwise-absent POSIX locales names and UTF-8 support under MSVC.
  61
  62 It is very useful when the compiler and the library actually give fine localization
  63 support, like GCC under Linux or MSVC under Windows.
  64
  65 \subsection posix_backend posix - POSIX 2008 C library
  66
  67 This backend is based on the latest POSIX 2008 standards, and uses POSIX api functions like
  68 \c newlocale, \c freelocale, \c strftime_l  etc. It is available on the Linux and Mac OS X
  69 platforms.
  70
  71 It gives you simple and ready-made localization support, most notably under Mac OS X where
  72 GCC's \c libstdc++ does not support locales.
  73
  74 \note The POSIX backend only supports UTF-8, single-byte, and double-byte encodings.
  75
  76 \subsection winapi_backend winapi - Win32 API.
  77
  78 The Win32API-based localization backend provides decent UTF-8/UTF-16 locale support.
  79 It is based on Windows API functions like \c GetLocaleInfoW, \c LCMapStringW, \c GetDateFormatW etc and
  80 provides good localization support even on the MinGW and Cygwin platforms, which normally have
  81 problems with this.
  82
  83 \note
  84
  85 - If you using GCC compiler under Windows you need GCC-4.x series to use it, GCC-3.4 is not supported
  86 - Only UTF-8 as narrow locale encoding and UTF-16 as wide encoding are supported.
  87
  88 \section supported_features_by_backends Supported Features
  89
  90 <table border="1" sellpadding="5" sellspacing="3">
  91 <tr>
  92   <th>Backend</th>
  93   <th>icu</th><th>posix</th><th>winapi</th><th>std</th>
  94 </tr>
  95 <tr>
  96   <th>Message Formatting</th>
  97   <td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td>
  98 </tr>
  99 <tr>
 100   <th>Non UTF-8 encodings</th>
 101   <td>Yes</td><td>Yes</td><td>No</td><td>Yes</td>
 102 </tr>
 103 <tr>
 104   <th>Date/Time Formatting/Parsing</th>
 105   <td>Yes</td><td>Formatting Only</td><td>Formatting Only</td><td>Formatting Only</td>
 106 </tr>
 107 <tr>
 108   <th>Monetary Formatting/Parsing</th>
 109   <td>Yes</td><td>Formatting Only</td><td>Formatting Only</td><td>Yes</td>
 110 </tr>
 111 <tr>
 112   <th>Number Formatting/Parsing</th>
 113   <td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td>
 114 </tr>
 115 <tr>
 116   <th>Numbers as Percent, Spelled Out</th>
 117   <td>Yes</td><td>No</td><td>No</td><td>No</td>
 118 </tr>
 119 <tr>
 120   <th>Case Manipulation</th>
 121   <td>Yes</td><td>Basic</td><td>Basic</td><td>Basic</td>
 122 </tr>
 123 <tr>
 124   <th>Collation</th>
 125   <td>Full</td><td>Linux - 1 level<br>Mac OS X - broken</td><td>3 levels</td><td>1 level</td>
 126 </tr>
 127 <tr>
 128   <th>Calendar</th>
 129   <td>Yes</td><td>Gregorian Only</td><td>Gregorian Only</td><td>Gregorian Only</td>
 130 </tr>
 131 <tr>
 132   <th>Boundary Analysis</th>
 133   <td>Yes</td><td>No</td><td>No</td><td>No</td>
 134 </tr>
 135 <tr>
 136   <th>Unicode Normalization</th>
 137   <td>Yes</td><td>No</td><td>Vista and above</td><td>No</td>
 138 </tr>
 139 <tr>
 140   <th>C++0x characters</th>
 141   <td>Yes</td><td>No</td><td>No</td><td>Yes</td>
 142 </tr>
 143 <tr>
 144   <th>OS Support</th>
 145   <td>Any</td><td>Linux, Mac OS X</td><td>Windows, Cygwin</td><td>Any</td>
 146 </tr>
 147 <tr>
 148   <th>Useful on</th>
 149   <td>Any Platform</td><td>Linux and Mac OS X</td><td>Windows/MinGW/Cygwin</td><td>Linux with GCC or Intel<br>Windows with MSVC</td>
 150 </tr>
 151 </table>
 152
 153
 154 \section using_localization_backends Using Localization Backends
 155
 156 Accessing a localization backend is done via the boost::locale::localization_backend_manager class.
 157
 158 You can create your own boost::locale::localization_backend_manager by starting with a global backend
 159 via the boost::locale::localization_backend_manager::global static member function and modifying it.
 160
 161 For example:
 162
 163 \code
 164     localization_backend_manager my = localization_backend_manager::global();
 165     // Get global backend
 166
 167     my.select("std");
 168     // select std backend as default
 169
 170     generator gen(my);
 171     // create a generator that uses this backend.
 172
 173     localization_backend_manager::global(my);
 174     // set this backend globally
 175
 176     generator gen2();
 177     // now this one would use the new global backend.
 178 \endcode
 179
 180 You can also create a mixture of several backends, using
 181 for example \c icu for one kind of operation and \c std
 182 for all others:
 183
 184 \code
 185     localization_backend_manager my = localization_backend_manager::global();
 186     // Get global backend
 187
 188     my.select("std");
 189     // select std backend as default for all categories
 190     my.select("icu",boundary_facet);
 191     // select icu backend for boundary analysis (since it is not supported by \c std)
 192 \endcode
 193
 194 */
 195
 196