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>
   7       ISO C++
   8     </keyword>
   9     <keyword>
  10       locale
  11     </keyword>
  12   </keywordset>
  13 </info>
  14
  15
  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 <section xml:id="locales.locale.req"><info><title>Requirements</title></info>
  24
  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 object that can be used to query for the
  43 thousands separator in the 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 </section>
  92
  93 <section xml:id="locales.locale.design"><info><title>Design</title></info>
  94
  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 </section>
 108
 109 <section xml:id="locales.locale.impl"><info><title>Implementation</title></info>
 110
 111
 112   <section xml:id="locale.impl.c"><info><title>Interacting with "C" locales</title></info>
 113
 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   </section>
 472 </section>
 473
 474 <section xml:id="locales.locale.future"><info><title>Future</title></info>
 475
 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 </section>
 513
 514 <bibliography xml:id="locales.locale.biblio"><info><title>Bibliography</title></info>
 515
 516
 517   <biblioentry>
 518     <citetitle>
 519       The GNU C Library
 520     </citetitle>
 521     <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
 522     <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
 523     <copyright>
 524       <year>2007</year>
 525       <holder>FSF</holder>
 526     </copyright>
 527     <pagenums>
 528       Chapters 6 Character Set Handling and 7 Locales and
 529       Internationalization
 530     </pagenums>
 531   </biblioentry>
 532
 533   <biblioentry>
 534     <citetitle>
 535       Correspondence
 536     </citetitle>
 537     <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
 538     <copyright>
 539       <year>2002</year>
 540       <holder/>
 541     </copyright>
 542   </biblioentry>
 543
 544   <biblioentry>
 545     <citetitle>
 546       ISO/IEC 14882:1998 Programming languages - C++
 547     </citetitle>
 548     <copyright>
 549       <year>1998</year>
 550       <holder>ISO</holder>
 551     </copyright>
 552   </biblioentry>
 553
 554   <biblioentry>
 555     <citetitle>
 556       ISO/IEC 9899:1999 Programming languages - C
 557     </citetitle>
 558     <copyright>
 559       <year>1999</year>
 560       <holder>ISO</holder>
 561     </copyright>
 562   </biblioentry>
 563
 564   <biblioentry>
 565       <title>
 566         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 567               xlink:href="http://www.opengroup.org/austin/">
 568       System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
 569         </link>
 570       </title>
 571     <copyright>
 572       <year>2008</year>
 573       <holder>
 574         The Open Group/The Institute of Electrical and Electronics
 575         Engineers, Inc.
 576       </holder>
 577     </copyright>
 578   </biblioentry>
 579
 580   <biblioentry>
 581     <citetitle>
 582       The C++ Programming Language, Special Edition
 583     </citetitle>
 584     <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
 585     <copyright>
 586       <year>2000</year>
 587       <holder>Addison Wesley, Inc.</holder>
 588     </copyright>
 589     <pagenums>Appendix D</pagenums>
 590     <publisher>
 591       <publishername>
 592         Addison Wesley
 593       </publishername>
 594     </publisher>
 595   </biblioentry>
 596
 597   <biblioentry>
 598     <citetitle>
 599       Standard C++ IOStreams and Locales
 600     </citetitle>
 601     <subtitle>
 602       Advanced Programmer's Guide and Reference
 603     </subtitle>
 604     <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
 605     <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
 606     <copyright>
 607       <year>2000</year>
 608       <holder>Addison Wesley Longman, Inc.</holder>
 609     </copyright>
 610     <publisher>
 611       <publishername>
 612         Addison Wesley Longman
 613       </publishername>
 614     </publisher>
 615   </biblioentry>
 616
 617 </bibliography>
 618
 619 </section>