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