ceph/src/boost/libs/locale/doc/default_encoding_under_windows.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 default_encoding_under_windows Default Encoding under Microsoft Windows
  12
  13 All modern operating systems use Unicode.
  14
  15 -   Unix operating system family use UTF-8 encoding by default.
  16 -   Microsoft Windows had migrated to Wide/UTF-16 API.
  17     The narrow encodings had been deprecated and the native OS API became so called "Wide API"
  18
  19 As a result of radically different approaches, it is very hard to write portable Unicode aware applications.
  20
  21 Boost Locale fully supports both narrow and wide API. The default character
  22 encoding is assumed to be UTF-8 on Windows.
  23
  24 So if the default operating system Locale is "English_USA.1252" the default
  25 locale for Boost.Locale on Windows would be "en_US.UTF-8".
  26
  27 When the created locale object is installed globally then any libraries
  28 that use \c std::codecvt for conversion between narrow API and the native
  29 wide API would handle UTF-8 correctly.
  30
  31 A good example of such library is Boost.Filesystem v3.
  32
  33 For example
  34
  35 \code
  36 #include <boost/locale.hpp>
  37 #include <boost/filesystem/path.hpp>
  38 #include <boost/filesystem/fstream.hpp>
  39
  40 int main()
  41 {
  42     // Create and install global locale
  43     std::locale::global(boost::locale::generator().generate(""));
  44     // Make boost.filesystem use it
  45     boost::filesystem::path::imbue(std::locale());
  46     // Now Works perfectly fine with UTF-8!
  47     boost::filesystem::ofstream hello("שלום.txt");
  48 }
  49
  50 \endcode
  51
  52 However such behavior may break existing software that assumes that the current
  53 encoding is single byte encodings like code page 1252.
  54
  55 \ref boost::locale::generator class has a property \ref boost::locale::generator::use_ansi_encoding() "use_ansi_encoding()"
  56 that allows to change the behavior to legacy one and select an ANSI code page as
  57 default system encoding.
  58
  59 So, when the current locale is "English_USA.1252" and the \c use_ansi_encoding is turned on
  60 then the default locale would be "en_US.windows-1252"
  61
  62 \note \c winapi backend does not support ANSI encodings, thus UTF-8 encoding is always used for narrow characters.
  63
  64 */
  65