libstdc++-v3/doc/xml/manual/locale.xml

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