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