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

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