123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110 |
- //
- // Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
- //
- // Distributed under the Boost Software License, Version 1.0. (See
- // accompanying file LICENSE_1_0.txt or copy at
- // http://www.boost.org/LICENSE_1_0.txt)
- //
- // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen
- /*!
- \page locale_gen Locale Generation
- 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 \c std::string). Boost.Locale uses the POSIX naming convention for locales,
- i.e. a locale is defined as <tt>language[_COUNTRY][.encoding][\@variant]</tt>, 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 \c UTF-8 or \c ISO-8859-1,
- and variant is additional options for specializing the locale, like \c euro or \c calendar=hebrew, see \ref locale_gen_variant.
- Note that each locale should include the encoding in order to handle \c char based strings correctly.
- \section locale_gen_basics Basics
- The class \ref boost::locale::generator "generator" provides tools to generate the locales we need. The simplest way to use
- \c generator is to create a locale and set it as the global one:
- \code
- #include <boost/locale.hpp>
-
- using namespace boost::locale;
- int main()
- {
- generator gen;
- // Create locale generator
- std::locale::global(gen(""));
- // "" - the system default locale, set
- // it globally
- }
- \endcode
- Of course we can also specify the locale manually
- \code
- std::locale loc = gen("en_US.UTF-8");
- // Use English, United States locale
- \endcode
- \note
- - Even if your application uses wide strings everywhere, you should specify the
- 8-bit encoding to use for 8-bit stream IO operations like \c cout or \c fstream.
- \n
- - The default locale is defined by the environment variables \c LC_CTYPE , \c LC_ALL , and \c LANG
- in that order (i.e. \c LC_CTYPE first and \c LANG last). On Windows, the library
- also queries the \c LOCALE_USER_DEFAULT option in the Win32 API when these variables
- are not set.
- \b Tip: Prefer using UTF-8 Unicode encoding over 8-bit encodings like the ISO-8859-X ones.
- 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
- \ref boost::locale::generator::categories() "categories" and \ref boost::locale::generator::characters() "characters"
- member functions of the \ref boost::locale::generator "generator" class.
- For example:
- \code
- generator gen;
- gen.characters(wchar_t_facet);
- gen.categories(collation_facet | formatting_facet);
- std::locale::global(gen("de_DE.UTF-8"));
- \endcode
- \section locale_gen_variant Variant
- The variant part of the locale (the part that comes after \@ symbol) is localization \ref using_localization_backends "back-end" dependent.
- \subsection locale_gen_variant_non_icu Non ICU Backends
- \ref posix_backend "POSIX" and \ref std_backend "std" back-ends use their own OS specific naming conventions and
- depend on the current OS configuration. For example typical Linux distribution provides \c euro for currency selection,
- \c cyrillic and \c latin for specification of language script.
- \ref winapi_backend "winapi" back-end does not support any variants.
- \subsection locale_gen_variant_icu ICU Backend
- 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.
- However in general it is represented as set of key=value pairs separated with a semicolon ";" For example:
- "@collation=phonebook;calendar=islamic-civil".
- Currently ICU supports following keys:
- - \c calendar - the calendar used for the current locale. For example: \c gregorian, \c japanese,
- \c buddhist, \c islamic, \c hebrew, \c chinese, \c islamic-civil.
- - \c collation - the collation order used for this locales, for example \c phonebook, \c pinyin, \c traditional,
- \c stroke, \c direct, \c posix.
- - \c currency - the currency used in this locale, the standard 3 letter code like USD or JPY.
- - \c numbers - the numbering system used, for example: \c latn, \c arab, \c thai.
- Please refer to CLDR and ICU documentation for exact list of keys and values:
- - <a href="http://userguide.icu-project.org/locale#TOC-Keywords">ICU User Guide/Locale/Keywords</a>
- - <a href="http://www.unicode.org/reports/tr35/">Unicode Locale Data Markup Language</a>
- */
|