libstdc++-v3/docs/html/22_locale/howto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   6    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
   7    <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22.">
   8    <meta name="GENERATOR" content="vi and eight fingers">
   9    <title>libstdc++-v3 HOWTO:  Chapter 22</title>
  10 <link rel=StyleSheet href="../lib3styles.css">
  11 </head>
  12 <body>
  13
  14 <h1 class="centered"><a name="top">Chapter 22:  Localization</a></h1>
  15
  16 <p>Chapter 22 deals with the C++ localization facilities.
  17 </p>
  18 <!-- I wanted to write that sentence in something requiring an exotic font,
  19      like Cryllic or Kanji.  Probably more work than such cuteness is worth,
  20      but I still think it'd be funny.
  21  -->
  22
  23
  24 <!-- ####################################################### -->
  25 <hr>
  26 <h1>Contents</h1>
  27 <ul>
  28    <li><a href="#1">class locale</a>
  29    <li><a href="#2">class codecvt</a>
  30    <li><a href="#3">class ctype</a>
  31    <li><a href="#4">class messages</a>
  32    <li><a href="#5">Bjarne Stroustrup on Locales</a>
  33    <li><a href="#6">Nathan Myers on Locales</a>
  34    <li><a href="#7">Correct Transformations</a>
  35 </ul>
  36
  37 <!-- ####################################################### -->
  38
  39 <hr>
  40 <h2><a name="1">class locale</a></h2>
  41    <p>Notes made during the implementation of locales can be found
  42       <a href="locale.html">here</a>.
  43    </p>
  44
  45 <hr>
  46 <h2><a name="2">class codecvt</a></h2>
  47    <p>Notes made during the implementation of codecvt can be found
  48       <a href="codecvt.html">here</a>.
  49    </p>
  50
  51    <p>The following is the abstract from the implementation notes:
  52    <blockquote>
  53    The standard class codecvt attempts to address conversions between
  54    different character encoding schemes. In particular, the standard
  55    attempts to detail conversions between the implementation-defined
  56    wide characters (hereafter referred to as wchar_t) and the standard
  57    type char that is so beloved in classic &quot;C&quot; (which can
  58    now be referred to as narrow characters.)  This document attempts
  59    to describe how the GNU libstdc++-v3 implementation deals with the
  60    conversion between wide and narrow characters, and also presents a
  61    framework for dealing with the huge number of other encodings that
  62    iconv can convert, including Unicode and UTF8. Design issues and
  63    requirements are addressed, and examples of correct usage for both
  64    the required specializations for wide and narrow characters and the
  65    implementation-provided extended functionality are given.
  66    </blockquote>
  67    </p>
  68
  69 <hr>
  70 <h2><a name="3">class ctype</a></h2>
  71    <p>Notes made during the implementation of ctype can be found
  72       <a href="ctype.html">here</a>.
  73    </p>
  74
  75 <hr>
  76 <h2><a name="4">class messages</a></h2>
  77    <p>Notes made during the implementation of messages can be found
  78       <a href="messages.html">here</a>.
  79    </p>
  80
  81 <hr>
  82 <h2><a name="5">Stroustrup on Locales</a></h2>
  83    <p>Dr. Bjarne Stroustrup has released a
  84       <a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a>
  85       to Appendix D of his book,
  86       <a href="http://www.research.att.com/~bs/3rd.html">The C++
  87       Programming Language (3rd Edition)</a>.  It is a detailed
  88       description of locales and how to use them.
  89    </p>
  90    <p>He also writes:
  91       <blockquote><em>
  92       Please note that I still consider this detailed description of
  93       locales beyond the needs of most C++ programmers.  It is written
  94       with experienced programmers in mind and novices will do best to
  95       avoid it.
  96       </em></blockquote>
  97    </p>
  98
  99 <hr>
 100 <h2><a name="6">Nathan Myers on Locales</a></h2>
 101    <p>An article entitled &quot;The Standard C++ Locale&quot; was
 102       published in Dr. Dobb's Journal and can be found
 103       <a href="http://www.cantrip.org/locale.html">here</a>.
 104    </p>
 105
 106 <hr>
 107 <h2><a name="7">Correct Transformations</a></h2>
 108    <!-- Jumping directly to here from chapter 21. -->
 109    <p>A very common question on newsgroups and mailing lists is, &quot;How
 110       do I do &lt;foo&gt; to a character string?&quot; where &lt;foo&gt; is
 111       a task such as changing all the letters to uppercase, to lowercase,
 112       testing for digits, etc.  A skilled and conscientious programmer
 113       will follow the question with another, &quot;And how do I make the
 114       code portable?&quot;
 115    </p>
 116    <p>(Poor innocent programmer, you have no idea the depths of trouble
 117       you are getting yourself into.  'Twould be best for your sanity if
 118       you dropped the whole idea and took up basket weaving instead.  No?
 119       Fine, you asked for it...)
 120    </p>
 121    <p>The task of changing the case of a letter or classifying a character
 122       as numeric, graphical, etc, all depends on the cultural context of the
 123       program at runtime.  So, first you must take the portability question
 124       into account.  Once you have localized the program to a particular
 125       natural language, only then can you perform the specific task.
 126       Unfortunately, specializing a function for a human language is not
 127       as simple as declaring
 128       <code> extern &quot;Danish&quot; int tolower (int); </code>.
 129    </p>
 130    <p>The C++ code to do all this proceeds in the same way.  First, a locale
 131       is created.  Then member functions of that locale are called to
 132       perform minor tasks.  Continuing the example from Chapter 21, we wish
 133       to use the following convenience functions:
 134    <pre>
 135    namespace std {
 136      template &lt;class charT&gt;
 137        charT
 138        toupper (charT c, const locale&amp; loc) const;
 139      template &lt;class charT&gt;
 140        charT
 141        tolower (charT c, const locale&amp; loc) const;
 142    }</pre>
 143       This function extracts the appropriate &quot;facet&quot; from the
 144       locale <em>loc</em> and calls the appropriate member function of that
 145       facet, passing <em>c</em> as its argument.  The resulting character
 146       is returned.
 147    </p>
 148    <p>For the C/POSIX locale, the results are the same as calling the
 149       classic C <code>toupper/tolower</code> function that was used in previous
 150       examples.  For other locales, the code should Do The Right Thing.
 151    </p>
 152    <p>Of course, these functions take a second argument, and the
 153       transformation algorithm's operator argument can only take a single
 154       parameter.  So we write simple wrapper structs to handle that.
 155    </p>
 156    <p>The next-to-final version of the code started in Chapter 21 looks like:
 157       <pre>
 158    #include &lt;iterator&gt;    // for back_inserter
 159    #include &lt;locale&gt;
 160    #include &lt;string&gt;
 161    #include &lt;algorithm&gt;
 162    #include &lt;cctype&gt;      // old &lt;ctype.h&gt;
 163
 164    struct Toupper
 165    {
 166        Toupper (std::locale const&amp; l) : loc(l) {;}
 167        char operator() (char c)  { return std::toupper(c,loc); }
 168    private:
 169        std::locale const&amp; loc;
 170    };
 171
 172    struct Tolower
 173    {
 174        Tolower (std::locale const&amp; l) : loc(l) {;}
 175        char operator() (char c)  { return std::tolower(c,loc); }
 176    private:
 177        std::locale const&amp; loc;
 178    };
 179
 180    int main ()
 181    {
 182       std::string  s ("Some Kind Of Initial Input Goes Here");
 183       Toupper      up   ( std::locale("C") );
 184       Tolower      down ( std::locale("C") );
 185
 186       // Change everything into upper case
 187       std::transform (s.begin(), s.end(), s.begin(),
 188                       up
 189                      );
 190
 191       // Change everything into lower case
 192       std::transform (s.begin(), s.end(), s.begin(),
 193                       down
 194                      );
 195
 196       // Change everything back into upper case, but store the
 197       // result in a different string
 198       std::string  capital_s;
 199       std::transform (s.begin(), s.end(), std::back_inserter(capital_s),
 200                       up
 201                      );
 202    }</pre>
 203    </p>
 204    <p>The final version of the code uses <code>bind2nd</code> to eliminate
 205       the wrapper structs, but the resulting code is tricky.  I have not
 206       shown it here because no compilers currently available to me will
 207       handle it.
 208    </p>
 209
 210
 211 <!-- ####################################################### -->
 212
 213 <hr>
 214 <p class="fineprint"><em>
 215 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 216 Comments and suggestions are welcome, and may be sent to
 217 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 218 </em></p>
 219
 220
 221 </body>
 222 </html>