OSDN Git Service

275534d36699c60dc513d859bdd0f18491aa4817
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / doc / xml / manual / locale.xml
1 <sect1 id="manual.localization.locales.locale" xreflabel="locale">
2 <?dbhtml filename="locale.html"?>
3  
4 <sect1info>
5   <keywordset>
6     <keyword>
7       ISO C++
8     </keyword>
9     <keyword>
10       locale
11     </keyword>
12   </keywordset>
13 </sect1info>
14
15 <title>locale</title>
16
17 <para>
18 Describes the basic locale object, including nested
19 classes id, facet, and the reference-counted implementation object,
20 class _Impl.
21 </para>
22
23 <sect2 id="locales.locale.req" xreflabel="locales.locale.req">
24 <title>Requirements</title>
25
26 <para>
27 Class locale is non-templatized and has two distinct types nested
28 inside of it:
29 </para>
30
31 <blockquote>
32 <para>
33 <emphasis>
34 class facet
35 22.1.1.1.2 Class locale::facet
36 </emphasis>
37 </para>
38 </blockquote>
39
40 <para>
41 Facets actually implement locale functionality. For instance, a facet
42 called numpunct is the data objects that can be used to query for the
43 thousands separator is in the German locale.
44 </para>
45
46 <para>
47 Literally, a facet is strictly defined:
48 </para>
49
50 <itemizedlist>
51   <listitem>
52     <para>
53       Containing the following public data member:
54     </para>
55     <para>
56       <code>static locale::id id;</code>
57     </para>
58   </listitem>
59
60   <listitem>
61     <para>
62       Derived from another facet:
63     </para>
64     <para>
65       <code>class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code>
66     </para>
67   </listitem>
68 </itemizedlist>
69
70 <para>
71 Of interest in this class are the memory management options explicitly
72 specified as an argument to facet's constructor. Each constructor of a
73 facet class takes a std::size_t __refs argument: if __refs == 0, the
74 facet is deleted when the locale containing it is destroyed. If __refs
75 == 1, the facet is not destroyed, even when it is no longer
76 referenced.
77 </para>
78
79 <blockquote>
80 <para>
81 <emphasis>
82 class id
83 22.1.1.1.3 - Class locale::id
84 </emphasis>
85 </para>
86 </blockquote>
87
88 <para>
89 Provides an index for looking up specific facets.
90 </para>
91 </sect2>
92
93 <sect2 id="locales.locale.design" xreflabel="locales.locale.design">
94 <title>Design</title>
95
96 <para>
97 The major design challenge is fitting an object-orientated and
98 non-global locale design on top of POSIX and other relevant standards,
99 which include the Single Unix (nee X/Open.)
100 </para>
101
102 <para>
103 Because C and earlier versions of POSIX fall down so completely,
104 portability is an issue.
105 </para>
106
107 </sect2>
108
109 <sect2 id="locales.locale.impl" xreflabel="locales.locale.impl">
110 <title>Implementation</title>
111
112   <sect3 id="locale.impl.c" xreflabel="locale.impl.c">
113     <title>Interacting with &quot;C&quot; locales</title>
114
115 <itemizedlist>
116    <listitem>
117      <para> 
118        <code>`locale -a`</code> displays available locales. 
119      </para>
120 <blockquote>
121 <programlisting>
122 af_ZA
123 ar_AE
124 ar_AE.utf8
125 ar_BH
126 ar_BH.utf8
127 ar_DZ
128 ar_DZ.utf8
129 ar_EG
130 ar_EG.utf8
131 ar_IN
132 ar_IQ
133 ar_IQ.utf8
134 ar_JO
135 ar_JO.utf8
136 ar_KW
137 ar_KW.utf8
138 ar_LB
139 ar_LB.utf8
140 ar_LY
141 ar_LY.utf8
142 ar_MA
143 ar_MA.utf8
144 ar_OM
145 ar_OM.utf8
146 ar_QA
147 ar_QA.utf8
148 ar_SA
149 ar_SA.utf8
150 ar_SD
151 ar_SD.utf8
152 ar_SY
153 ar_SY.utf8
154 ar_TN
155 ar_TN.utf8
156 ar_YE
157 ar_YE.utf8
158 be_BY
159 be_BY.utf8
160 bg_BG
161 bg_BG.utf8
162 br_FR
163 bs_BA
164 C
165 ca_ES
166 ca_ES@euro
167 ca_ES.utf8
168 ca_ES.utf8@euro
169 cs_CZ
170 cs_CZ.utf8
171 cy_GB
172 da_DK
173 da_DK.iso885915
174 da_DK.utf8
175 de_AT
176 de_AT@euro
177 de_AT.utf8
178 de_AT.utf8@euro
179 de_BE
180 de_BE@euro
181 de_BE.utf8
182 de_BE.utf8@euro
183 de_CH
184 de_CH.utf8
185 de_DE
186 de_DE@euro
187 de_DE.utf8
188 de_DE.utf8@euro
189 de_LU
190 de_LU@euro
191 de_LU.utf8
192 de_LU.utf8@euro
193 el_GR
194 el_GR.utf8
195 en_AU
196 en_AU.utf8
197 en_BW
198 en_BW.utf8
199 en_CA
200 en_CA.utf8
201 en_DK
202 en_DK.utf8
203 en_GB
204 en_GB.iso885915
205 en_GB.utf8
206 en_HK
207 en_HK.utf8
208 en_IE
209 en_IE@euro
210 en_IE.utf8
211 en_IE.utf8@euro
212 en_IN
213 en_NZ
214 en_NZ.utf8
215 en_PH
216 en_PH.utf8
217 en_SG
218 en_SG.utf8
219 en_US
220 en_US.iso885915
221 en_US.utf8
222 en_ZA
223 en_ZA.utf8
224 en_ZW
225 en_ZW.utf8
226 es_AR
227 es_AR.utf8
228 es_BO
229 es_BO.utf8
230 es_CL
231 es_CL.utf8
232 es_CO
233 es_CO.utf8
234 es_CR
235 es_CR.utf8
236 es_DO
237 es_DO.utf8
238 es_EC
239 es_EC.utf8
240 es_ES
241 es_ES@euro
242 es_ES.utf8
243 es_ES.utf8@euro
244 es_GT
245 es_GT.utf8
246 es_HN
247 es_HN.utf8
248 es_MX
249 es_MX.utf8
250 es_NI
251 es_NI.utf8
252 es_PA
253 es_PA.utf8
254 es_PE
255 es_PE.utf8
256 es_PR
257 es_PR.utf8
258 es_PY
259 es_PY.utf8
260 es_SV
261 es_SV.utf8
262 es_US
263 es_US.utf8
264 es_UY
265 es_UY.utf8
266 es_VE
267 es_VE.utf8
268 et_EE
269 et_EE.utf8
270 eu_ES
271 eu_ES@euro
272 eu_ES.utf8
273 eu_ES.utf8@euro
274 fa_IR
275 fi_FI
276 fi_FI@euro
277 fi_FI.utf8
278 fi_FI.utf8@euro
279 fo_FO
280 fo_FO.utf8
281 fr_BE
282 fr_BE@euro
283 fr_BE.utf8
284 fr_BE.utf8@euro
285 fr_CA
286 fr_CA.utf8
287 fr_CH
288 fr_CH.utf8
289 fr_FR
290 fr_FR@euro
291 fr_FR.utf8
292 fr_FR.utf8@euro
293 fr_LU
294 fr_LU@euro
295 fr_LU.utf8
296 fr_LU.utf8@euro
297 ga_IE
298 ga_IE@euro
299 ga_IE.utf8
300 ga_IE.utf8@euro
301 gl_ES
302 gl_ES@euro
303 gl_ES.utf8
304 gl_ES.utf8@euro
305 gv_GB
306 gv_GB.utf8
307 he_IL
308 he_IL.utf8
309 hi_IN
310 hr_HR
311 hr_HR.utf8
312 hu_HU
313 hu_HU.utf8
314 id_ID
315 id_ID.utf8
316 is_IS
317 is_IS.utf8
318 it_CH
319 it_CH.utf8
320 it_IT
321 it_IT@euro
322 it_IT.utf8
323 it_IT.utf8@euro
324 iw_IL
325 iw_IL.utf8
326 ja_JP.eucjp
327 ja_JP.utf8
328 ka_GE
329 kl_GL
330 kl_GL.utf8
331 ko_KR.euckr
332 ko_KR.utf8
333 kw_GB
334 kw_GB.utf8
335 lt_LT
336 lt_LT.utf8
337 lv_LV
338 lv_LV.utf8
339 mi_NZ
340 mk_MK
341 mk_MK.utf8
342 mr_IN
343 ms_MY
344 ms_MY.utf8
345 mt_MT
346 mt_MT.utf8
347 nl_BE
348 nl_BE@euro
349 nl_BE.utf8
350 nl_BE.utf8@euro
351 nl_NL
352 nl_NL@euro
353 nl_NL.utf8
354 nl_NL.utf8@euro
355 nn_NO
356 nn_NO.utf8
357 no_NO
358 no_NO.utf8
359 oc_FR
360 pl_PL
361 pl_PL.utf8
362 POSIX
363 pt_BR
364 pt_BR.utf8
365 pt_PT
366 pt_PT@euro
367 pt_PT.utf8
368 pt_PT.utf8@euro
369 ro_RO
370 ro_RO.utf8
371 ru_RU
372 ru_RU.koi8r
373 ru_RU.utf8
374 ru_UA
375 ru_UA.utf8
376 se_NO
377 sk_SK
378 sk_SK.utf8
379 sl_SI
380 sl_SI.utf8
381 sq_AL
382 sq_AL.utf8
383 sr_YU
384 sr_YU@cyrillic
385 sr_YU.utf8
386 sr_YU.utf8@cyrillic
387 sv_FI
388 sv_FI@euro
389 sv_FI.utf8
390 sv_FI.utf8@euro
391 sv_SE
392 sv_SE.iso885915
393 sv_SE.utf8
394 ta_IN
395 te_IN
396 tg_TJ
397 th_TH
398 th_TH.utf8
399 tl_PH
400 tr_TR
401 tr_TR.utf8
402 uk_UA
403 uk_UA.utf8
404 ur_PK
405 uz_UZ
406 vi_VN
407 vi_VN.tcvn
408 wa_BE
409 wa_BE@euro
410 yi_US
411 zh_CN
412 zh_CN.gb18030
413 zh_CN.gbk
414 zh_CN.utf8
415 zh_HK
416 zh_HK.utf8
417 zh_TW
418 zh_TW.euctw
419 zh_TW.utf8
420 </programlisting>
421 </blockquote>
422 </listitem>
423    
424    <listitem>
425      <para> 
426        <code>`locale`</code> displays environmental variables that
427        impact how locale("") will be deduced.
428      </para>
429 <blockquote>
430 <programlisting>
431 LANG=en_US
432 LC_CTYPE="en_US"
433 LC_NUMERIC="en_US"
434 LC_TIME="en_US"
435 LC_COLLATE="en_US"
436 LC_MONETARY="en_US"
437 LC_MESSAGES="en_US"
438 LC_PAPER="en_US"
439 LC_NAME="en_US"
440 LC_ADDRESS="en_US"
441 LC_TELEPHONE="en_US"
442 LC_MEASUREMENT="en_US"
443 LC_IDENTIFICATION="en_US"
444 LC_ALL=
445 </programlisting>
446 </blockquote>
447 </listitem>
448 </itemizedlist>
449
450 <para>
451 From Josuttis, p. 697-698, which says, that "there is only *one*
452 relation (of the C++ locale mechanism) to the C locale mechanism: the
453 global C locale is modified if a named C++ locale object is set as the
454 global locale" (emphasis Paolo), that is:
455 </para>
456
457 <programlisting>std::locale::global(std::locale(""));</programlisting>
458
459 <para>affects the C functions as if the following call was made:</para>
460
461 <programlisting>std::setlocale(LC_ALL, "");</programlisting>
462
463 <para>
464   On the other hand, there is *no* vice versa, that is, calling
465   setlocale has *no* whatsoever on the C++ locale mechanism, in
466   particular on the working of locale(""), which constructs the locale
467   object from the environment of the running program, that is, in
468   practice, the set of LC_ALL, LANG, etc. variable of the shell.
469 </para>
470
471   </sect3>
472 </sect2>
473
474 <sect2 id="locales.locale.future" xreflabel="locales.locale.future">
475 <title>Future</title>
476
477 <itemizedlist>
478    <listitem>
479      <para>
480        Locale initialization: at what point does _S_classic, _S_global
481        get initialized? Can named locales assume this initialization
482        has already taken place? 
483      </para>
484      </listitem>
485
486    <listitem>
487      <para> 
488        Document how named locales error check when filling data
489        members. I.e., a fr_FR locale that doesn't have
490        numpunct::truename(): does it use "true"? Or is it a blank
491        string? What's the convention? 
492    </para>
493    </listitem>
494
495    <listitem>
496      <para> 
497        Explain how locale aliasing happens. When does "de_DE" use "de"
498        information? What is the rule for locales composed of just an
499        ISO language code (say, "de") and locales with both an ISO
500        language code and ISO country code (say, "de_DE"). 
501      </para>
502    </listitem>
503
504    <listitem>
505      <para> 
506        What should non-required facet instantiations do?  If the
507        generic implementation is provided, then how to end-users
508        provide specializations? 
509    </para>
510    </listitem>
511 </itemizedlist>
512 </sect2>
513
514 <bibliography id="locales.locale.biblio" xreflabel="locales.locale.biblio">
515 <title>Bibliography</title>
516
517   <biblioentry>
518     <title>
519       The GNU C Library
520     </title>
521
522     <author>
523       <surname>McGrath</surname>
524       <firstname>Roland</firstname>
525     </author>
526     <author>
527       <surname>Drepper</surname>
528       <firstname>Ulrich</firstname>
529     </author>
530
531     <copyright>
532       <year>2007</year>
533       <holder>FSF</holder>
534     </copyright>
535     <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums>
536
537   </biblioentry> 
538
539   <biblioentry>
540     <title>
541       Correspondence
542     </title>
543
544     <author>
545       <surname>Drepper</surname>
546       <firstname>Ulrich</firstname>
547     </author>
548
549     <copyright>
550       <year>2002</year>
551       <holder></holder>
552     </copyright>
553   </biblioentry> 
554
555   <biblioentry>
556     <title>
557       ISO/IEC 14882:1998 Programming languages - C++
558     </title>
559
560     <copyright>
561       <year>1998</year>
562       <holder>ISO</holder>
563     </copyright>
564   </biblioentry> 
565
566   <biblioentry>
567     <title>
568       ISO/IEC 9899:1999 Programming languages - C
569     </title>
570
571     <copyright>
572       <year>1999</year>
573       <holder>ISO</holder>
574     </copyright>
575   </biblioentry> 
576
577   <biblioentry>
578     <title>
579       System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
580     </title>
581
582     <copyright>
583       <year>1999</year>
584       <holder>
585       The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder>
586     </copyright>
587
588     <biblioid>
589       <ulink url="http://www.opennc.org/austin/docreg.html">
590       </ulink>
591     </biblioid>
592
593   </biblioentry> 
594
595   <biblioentry>
596     <title>
597       The C++ Programming Language, Special Edition
598     </title>
599     
600     <author>
601       <surname>Stroustrup</surname>
602       <firstname>Bjarne</firstname>
603     </author>
604
605     <copyright>
606       <year>2000</year>
607       <holder>Addison Wesley, Inc.</holder>
608     </copyright>
609     <pagenums>Appendix D</pagenums>
610
611     <publisher>
612       <publishername>
613         Addison Wesley
614       </publishername>
615     </publisher>
616
617   </biblioentry> 
618
619
620   <biblioentry>
621     <title>
622       Standard C++ IOStreams and Locales
623     </title>
624     <subtitle>
625       Advanced Programmer's Guide and Reference
626     </subtitle>
627     
628     <author>
629       <surname>Langer</surname>
630       <firstname>Angelika</firstname>
631     </author>
632
633     <author>
634       <surname>Kreft</surname>
635       <firstname>Klaus</firstname>
636     </author>
637
638     <copyright>
639       <year>2000</year>
640       <holder>Addison Wesley Longman, Inc.</holder>
641     </copyright>
642
643     <publisher>
644       <publishername>
645         Addison Wesley Longman
646       </publishername>
647     </publisher>
648
649   </biblioentry> 
650
651 </bibliography>
652
653 </sect1>