libstdc++-v3/docs/html/22_locale/locale.html

   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">
   5
   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="bkoz@redhat.com (Benjamin Kosnik)" />
  10    <meta name="KEYWORDS" content="HOWTO, libstdc++, locale name LC_ALL" />
  11    <meta name="DESCRIPTION" content="Notes on the locale implementation." />
  12    <title>Notes on the locale implementation.</title>
  13 <link rel="StyleSheet" href="../lib3styles.css" />
  14 </head>
  15 <body>
  16   <h1>
  17   Notes on the locale implementation.
  18   </h1>
  19 <em>
  20 prepared by Benjamin Kosnik (bkoz@redhat.com) on October 14, 2002
  21 </em>
  22
  23 <h2>
  24 1. Abstract
  25 </h2>
  26 <p>
  27 Describes the basic locale object, including nested
  28 classes id, facet, and the reference-counted implementation object,
  29 class _Impl.
  30 </p>
  31
  32 <h2>
  33 2. What the standard says
  34 </h2>
  35 Class locale is non-templatized and has two distinct types nested
  36 inside of it:
  37
  38 <blockquote>
  39 <em>
  40 class facet
  41 22.1.1.1.2 Class locale::facet
  42 </em>
  43 </blockquote>
  44
  45 <p>
  46 Facets actually implement locale functionality. For instance, a facet
  47 called numpunct is the data objects that can be used to query for the
  48 thousands separator is in the German locale.
  49 </p>
  50
  51 Literally, a facet is strictly defined:
  52 <ul>
  53   <li>containing the following public data member:
  54   <p>
  55   <code>static locale::id id;</code>
  56   </p>
  57   </li>
  58
  59   <li>derived from another facet:
  60   <p>
  61   <code> class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code>
  62   </p>
  63   </li>
  64 </ul>
  65
  66 <p>
  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 </p>
  74
  75 <blockquote>
  76 <em>
  77 class id
  78 22.1.1.1.3 - Class locale::id
  79 </em>
  80 </blockquote>
  81
  82 <p>
  83 Provides an index for looking up specific facets.
  84 </p>
  85
  86
  87 <h2>
  88 3. Interacting with &quot;C&quot; locales.
  89 </h2>
  90
  91 <p>
  92 Some help on determining the underlying support for locales on a system.
  93 Note, this is specific to linux (and glibc-2.3.x)
  94 </p>
  95
  96 <ul>
  97    <li> <code>`locale -a`</code> displays available locales.
  98 <blockquote>
  99 <pre>
 100 af_ZA
 101 ar_AE
 102 ar_AE.utf8
 103 ar_BH
 104 ar_BH.utf8
 105 ar_DZ
 106 ar_DZ.utf8
 107 ar_EG
 108 ar_EG.utf8
 109 ar_IN
 110 ar_IQ
 111 ar_IQ.utf8
 112 ar_JO
 113 ar_JO.utf8
 114 ar_KW
 115 ar_KW.utf8
 116 ar_LB
 117 ar_LB.utf8
 118 ar_LY
 119 ar_LY.utf8
 120 ar_MA
 121 ar_MA.utf8
 122 ar_OM
 123 ar_OM.utf8
 124 ar_QA
 125 ar_QA.utf8
 126 ar_SA
 127 ar_SA.utf8
 128 ar_SD
 129 ar_SD.utf8
 130 ar_SY
 131 ar_SY.utf8
 132 ar_TN
 133 ar_TN.utf8
 134 ar_YE
 135 ar_YE.utf8
 136 be_BY
 137 be_BY.utf8
 138 bg_BG
 139 bg_BG.utf8
 140 br_FR
 141 bs_BA
 142 C
 143 ca_ES
 144 ca_ES@euro
 145 ca_ES.utf8
 146 ca_ES.utf8@euro
 147 cs_CZ
 148 cs_CZ.utf8
 149 cy_GB
 150 da_DK
 151 da_DK.iso885915
 152 da_DK.utf8
 153 de_AT
 154 de_AT@euro
 155 de_AT.utf8
 156 de_AT.utf8@euro
 157 de_BE
 158 de_BE@euro
 159 de_BE.utf8
 160 de_BE.utf8@euro
 161 de_CH
 162 de_CH.utf8
 163 de_DE
 164 de_DE@euro
 165 de_DE.utf8
 166 de_DE.utf8@euro
 167 de_LU
 168 de_LU@euro
 169 de_LU.utf8
 170 de_LU.utf8@euro
 171 el_GR
 172 el_GR.utf8
 173 en_AU
 174 en_AU.utf8
 175 en_BW
 176 en_BW.utf8
 177 en_CA
 178 en_CA.utf8
 179 en_DK
 180 en_DK.utf8
 181 en_GB
 182 en_GB.iso885915
 183 en_GB.utf8
 184 en_HK
 185 en_HK.utf8
 186 en_IE
 187 en_IE@euro
 188 en_IE.utf8
 189 en_IE.utf8@euro
 190 en_IN
 191 en_NZ
 192 en_NZ.utf8
 193 en_PH
 194 en_PH.utf8
 195 en_SG
 196 en_SG.utf8
 197 en_US
 198 en_US.iso885915
 199 en_US.utf8
 200 en_ZA
 201 en_ZA.utf8
 202 en_ZW
 203 en_ZW.utf8
 204 es_AR
 205 es_AR.utf8
 206 es_BO
 207 es_BO.utf8
 208 es_CL
 209 es_CL.utf8
 210 es_CO
 211 es_CO.utf8
 212 es_CR
 213 es_CR.utf8
 214 es_DO
 215 es_DO.utf8
 216 es_EC
 217 es_EC.utf8
 218 es_ES
 219 es_ES@euro
 220 es_ES.utf8
 221 es_ES.utf8@euro
 222 es_GT
 223 es_GT.utf8
 224 es_HN
 225 es_HN.utf8
 226 es_MX
 227 es_MX.utf8
 228 es_NI
 229 es_NI.utf8
 230 es_PA
 231 es_PA.utf8
 232 es_PE
 233 es_PE.utf8
 234 es_PR
 235 es_PR.utf8
 236 es_PY
 237 es_PY.utf8
 238 es_SV
 239 es_SV.utf8
 240 es_US
 241 es_US.utf8
 242 es_UY
 243 es_UY.utf8
 244 es_VE
 245 es_VE.utf8
 246 et_EE
 247 et_EE.utf8
 248 eu_ES
 249 eu_ES@euro
 250 eu_ES.utf8
 251 eu_ES.utf8@euro
 252 fa_IR
 253 fi_FI
 254 fi_FI@euro
 255 fi_FI.utf8
 256 fi_FI.utf8@euro
 257 fo_FO
 258 fo_FO.utf8
 259 fr_BE
 260 fr_BE@euro
 261 fr_BE.utf8
 262 fr_BE.utf8@euro
 263 fr_CA
 264 fr_CA.utf8
 265 fr_CH
 266 fr_CH.utf8
 267 fr_FR
 268 fr_FR@euro
 269 fr_FR.utf8
 270 fr_FR.utf8@euro
 271 fr_LU
 272 fr_LU@euro
 273 fr_LU.utf8
 274 fr_LU.utf8@euro
 275 ga_IE
 276 ga_IE@euro
 277 ga_IE.utf8
 278 ga_IE.utf8@euro
 279 gl_ES
 280 gl_ES@euro
 281 gl_ES.utf8
 282 gl_ES.utf8@euro
 283 gv_GB
 284 gv_GB.utf8
 285 he_IL
 286 he_IL.utf8
 287 hi_IN
 288 hr_HR
 289 hr_HR.utf8
 290 hu_HU
 291 hu_HU.utf8
 292 id_ID
 293 id_ID.utf8
 294 is_IS
 295 is_IS.utf8
 296 it_CH
 297 it_CH.utf8
 298 it_IT
 299 it_IT@euro
 300 it_IT.utf8
 301 it_IT.utf8@euro
 302 iw_IL
 303 iw_IL.utf8
 304 ja_JP.eucjp
 305 ja_JP.utf8
 306 ka_GE
 307 kl_GL
 308 kl_GL.utf8
 309 ko_KR.euckr
 310 ko_KR.utf8
 311 kw_GB
 312 kw_GB.utf8
 313 lt_LT
 314 lt_LT.utf8
 315 lv_LV
 316 lv_LV.utf8
 317 mi_NZ
 318 mk_MK
 319 mk_MK.utf8
 320 mr_IN
 321 ms_MY
 322 ms_MY.utf8
 323 mt_MT
 324 mt_MT.utf8
 325 nl_BE
 326 nl_BE@euro
 327 nl_BE.utf8
 328 nl_BE.utf8@euro
 329 nl_NL
 330 nl_NL@euro
 331 nl_NL.utf8
 332 nl_NL.utf8@euro
 333 nn_NO
 334 nn_NO.utf8
 335 no_NO
 336 no_NO.utf8
 337 oc_FR
 338 pl_PL
 339 pl_PL.utf8
 340 POSIX
 341 pt_BR
 342 pt_BR.utf8
 343 pt_PT
 344 pt_PT@euro
 345 pt_PT.utf8
 346 pt_PT.utf8@euro
 347 ro_RO
 348 ro_RO.utf8
 349 ru_RU
 350 ru_RU.koi8r
 351 ru_RU.utf8
 352 ru_UA
 353 ru_UA.utf8
 354 se_NO
 355 sk_SK
 356 sk_SK.utf8
 357 sl_SI
 358 sl_SI.utf8
 359 sq_AL
 360 sq_AL.utf8
 361 sr_YU
 362 sr_YU@cyrillic
 363 sr_YU.utf8
 364 sr_YU.utf8@cyrillic
 365 sv_FI
 366 sv_FI@euro
 367 sv_FI.utf8
 368 sv_FI.utf8@euro
 369 sv_SE
 370 sv_SE.iso885915
 371 sv_SE.utf8
 372 ta_IN
 373 te_IN
 374 tg_TJ
 375 th_TH
 376 th_TH.utf8
 377 tl_PH
 378 tr_TR
 379 tr_TR.utf8
 380 uk_UA
 381 uk_UA.utf8
 382 ur_PK
 383 uz_UZ
 384 vi_VN
 385 vi_VN.tcvn
 386 wa_BE
 387 wa_BE@euro
 388 yi_US
 389 zh_CN
 390 zh_CN.gb18030
 391 zh_CN.gbk
 392 zh_CN.utf8
 393 zh_HK
 394 zh_HK.utf8
 395 zh_TW
 396 zh_TW.euctw
 397 zh_TW.utf8
 398 </pre>
 399 </blockquote>
 400 </li>
 401
 402    <li> <code>`locale`</code> displays environmental variables
 403    that impact how locale("") will be deduced.
 404
 405 <blockquote>
 406 <pre>
 407 LANG=en_US
 408 LC_CTYPE="en_US"
 409 LC_NUMERIC="en_US"
 410 LC_TIME="en_US"
 411 LC_COLLATE="en_US"
 412 LC_MONETARY="en_US"
 413 LC_MESSAGES="en_US"
 414 LC_PAPER="en_US"
 415 LC_NAME="en_US"
 416 LC_ADDRESS="en_US"
 417 LC_TELEPHONE="en_US"
 418 LC_MEASUREMENT="en_US"
 419 LC_IDENTIFICATION="en_US"
 420 LC_ALL=
 421 </pre>
 422 </blockquote>
 423 </li>
 424 </ul>
 425
 426 <p>
 427 From Josuttis, p. 697-698, which says, that "there is only *one*
 428 relation (of the C++ locale mechanism) to the C locale mechanism: the
 429 global C locale is modified if a named C++ locale object is set as the
 430 global locale" (emphasis Paolo), that is:
 431 </p>
 432     <code>std::locale::global(std::locale(""));</code>
 433
 434 <p>affects the C functions as if the following call was made:</p>
 435
 436     <code>std::setlocale(LC_ALL, "");</code>
 437
 438 <p>
 439 On the other hand, there is *no* viceversa, that is, calling setlocale
 440 has *no* whatsoever on the C++ locale mechanism, in particular on the
 441 working of locale(""), which constructs the locale object from the
 442 environment of the running program, that is, in practice, the set of
 443 LC_ALL, LANG, etc. variable of the shell.
 444 </p>
 445
 446
 447 <h2>
 448 4. Design
 449 </h2>
 450
 451
 452 <p>
 453 The major design challenge is fitting an object-orientated and
 454 non-global locale design ontop of POSIX and other relevant stanards,
 455 which include the Single Unix (nee X/Open.)
 456 </p>
 457
 458 <p>
 459 Because POSIX falls down so completely, portibility is an issue.
 460 </p>
 461
 462 class _Impl
 463 The internal representation of the std::locale object.
 464
 465
 466 <h2>
 467 5.  Examples
 468 </h2>
 469
 470 More information can be found in the following testcases:
 471 <ul>
 472 <li> testsuite/22_locale/all   </li>
 473 </ul>
 474
 475 <h2>
 476 6.  Unresolved Issues
 477 </h2>
 478
 479 <ul>
 480    <li> locale initialization: at what point does _S_classic,
 481    _S_global get initialized? Can named locales assume this
 482    initialization has already taken place? </li>
 483
 484    <li> document how named locales error check when filling data
 485    members. Ie, 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? </li>
 488
 489    <li> explain how locale aliasing happens. When does "de_DE"
 490    use "de" information? What is the rule for locales composed of
 491    just an ISO language code (say, "de") and locales with both an
 492    ISO language code and ISO country code (say, "de_DE"). </li>
 493
 494    <li> what should non-required facet instantiations do?  If the
 495    generic implemenation is provided, then how to end-users
 496    provide specializations? </li>
 497 </ul>
 498
 499 <h2>
 500 7. Acknowledgments
 501 </h2>
 502
 503 <h2>
 504 8. Bibliography / Referenced Documents
 505 </h2>
 506
 507 Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
 508
 509 <p>
 510 Drepper, Ulrich, Numerous, late-night email correspondence
 511 </p>
 512
 513 <p>
 514 ISO/IEC 14882:1998 Programming languages - C++
 515 </p>
 516
 517 <p>
 518 ISO/IEC 9899:1999 Programming languages - C
 519 </p>
 520
 521 <p>
 522 Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
 523 </p>
 524
 525 <p>
 526 Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
 527 </p>
 528
 529 <p>
 530 System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
 531 The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
 532 http://www.opennc.org/austin/docreg.html
 533 </p>
 534
 535 </body>
 536 </html>
 537
 538