• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
13By default, Boost.Locale uses ICU for all localization and text manipulation tasks.
14This is the most powerful library available, but sometimes we don't need
15the full power of this library or we want to reduce dependencies from third-party
16libraries, and ICU is by no means a small library.
17
18Boost.Locale provides an option to use non-ICU based localization
19backends. Although usually less powerful, these often provide all you need:
20message formatting, currency, date, time, number formatting, basic collation and
21case 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
25There 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
37All 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
53This localization backend is based on the standard C++ library.
54
55It is supported on all platforms, but is only actually useful on platforms where
56the standard library supports locales besides "C" and "POSIX": on Linux with GCC
57or Intel compilers, and under the MSVC compiler.
58
59It works around some common standard library bugs like invalid UTF-8 generation for numeric
60formatting, and it gives otherwise-absent POSIX locales names and UTF-8 support under MSVC.
61
62It is very useful when the compiler and the library actually give fine localization
63support, like GCC under Linux or MSVC under Windows.
64
65\subsection posix_backend posix - POSIX 2008 C library
66
67This 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
69platforms.
70
71It gives you simple and ready-made localization support, most notably under Mac OS X where
72GCC'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
78The Win32API-based localization backend provides decent UTF-8/UTF-16 locale support.
79It is based on Windows API functions like \c GetLocaleInfoW, \c LCMapStringW, \c GetDateFormatW etc and
80provides good localization support even on the MinGW and Cygwin platforms, which normally have
81problems 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
156Accessing a localization backend is done via the boost::locale::localization_backend_manager class.
157
158You can create your own boost::locale::localization_backend_manager by starting with a global backend
159via the boost::locale::localization_backend_manager::global static member function and modifying it.
160
161For 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
180You can also create a mixture of several backends, using
181for example \c icu for one kind of operation and \c std
182for 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
197