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

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