[thirdparty/gcc.git] / libstdc++-v3 / docs / html / 22_locale / locale.html

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
          PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
   <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
   <meta name="DESCRIPTION" content="Notes on the locale implementation." />
   <title>Notes on the locale implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
  <h1>
  Notes on the locale implementation.
  </h1>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</em>

<h2>
1. Abstract Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</h2>
<p>
</p>

<h2>
2. What the standard says
</h2>
See Chapter 22 of the standard.


<h2>
3. Problems with &quot;C&quot; locales : global locales, termination.
</h2>

<p>
The major problem is fitting an object-orientated and non-global locale
design ontop of POSIX and other relevant stanards, which include the
Single Unix (nee X/Open.)

Because POSIX falls down so completely, portibility is an issue.
</p>

<h2>
4. Design
</h2>
Class locale in non-templatized and has three distinct types nested
inside of it:

class facet
22.1.1.1.2 Class locale::facet

Facets actually implement locale functionality. For instance, a facet
called numpunct is the data objects that can be used to query for the
thousands separator is in the German locale.

Literally, a facet is strictly defined:
 - containing 
public:
  static locale::id id;

- or derived from another facet

The only other thing of interest in this class is the memory
management of facets. Each constructor of a facet class takes a
std::size_t __refs argument: if __refs == 0, the facet is deleted when
the locale containing it is destroyed. If __refs == 1, the facet is
not destroyed, even when it is no longer referenced.


class id
Provides an index for looking up specific facets.

class _Impl
The internal representation of the std::locale object.

<h2>
5.  Relationship to traditional "C" locales.
</h2>

From Josuttis, p. 697-698, which says, that "there is only *one*
relation (of the C++ locale mechanism) to the C locale mechanism: the
global C locale is modified if a named C++ locale object is set as the
global locale" (emphasis Paolo), that is:

    std::locale::global(std::locale(""));

affects the C functions as if the following call was made:

    std::setlocale(LC_ALL, "");

On the other hand, there is *no* viceversa, that is, calling setlocale
has *no* whatsoever on the C++ locale mechanism, in particular on the
working of locale(""), which constructs the locale object from the
environment of the running program, that is, in practice, the set of
LC_ALL, LANG, etc. variable of the shell.

<h2>
5.  Examples
</h2>

<pre>
  typedef __locale_t locale;
</pre>

More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/all   </li>
</ul>

<h2>
6.  Unresolved Issues
</h2>

<ul>
   <li> locale -a displays available locales on linux </li>

   <li> locale initialization: at what point does _S_classic,
   _S_global get initialized? Can named locales assume this
   initialization has already taken place? </li>

   <li> document how named locales error check when filling data
   members. Ie, a fr_FR locale that doesn't have
   numpunct::truename(): does it use "true"? Or is it a blank
   string? What's the convention? </li>

   <li> explain how locale aliasing happens. When does "de_DE"
   use "de" information? What is the rule for locales composed of
   just an ISO language code (say, "de") and locales with both an
   ISO language code and ISO country code (say, "de_DE"). </li>

   <li> what should non-required facet instantiations do?  If the
   generic implemenation is provided, then how to end-users
   provide specializations? </li>
</ul>

<h2>
7. Acknowledgments
</h2>

<h2>
8. Bibliography / Referenced Documents
</h2>

Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;

<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>

<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>

<p>
ISO/IEC 9899:1999 Programming languages - C
</p>

<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>

<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>

<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html
</p>

</body>
</html>
Commit	Line	Data
ba43f4eb JW	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
5d5e5e4e	6	<head>
64a6f971 JW	7	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
	8	<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
	9	<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
	10	<meta name="DESCRIPTION" content="Notes on the locale implementation." />
	11	<title>Notes on the locale implementation.</title>
	12	<link rel="StyleSheet" href="../lib3styles.css" />
1860e6ab JW	13	</head>
1860e6ab JW	14	<body>
5d5e5e4e	15	<h1>
04807c28	16	Notes on the locale implementation.
5d5e5e4e	17	</h1>
64a6f971	18	<em>
33590f13	19	prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
64a6f971	20	</em>
04807c28	21
5d5e5e4e	22	<h2>
0214010c BK	23	1. Abstract Describes the basic locale object, including nested
	24	classes id, facet, and the reference-counted implementation object,
	25	class _Impl.
5d5e5e4e PE	26	</h2>
	27	<p>
	28	</p>
04807c28	29
5d5e5e4e	30	<h2>
04807c28	31	2. What the standard says
5d5e5e4e	32	</h2>
64a6f971	33	See Chapter 22 of the standard.
04807c28 BK	34
04807c28 BK	35
5d5e5e4e	36	<h2>
04807c28	37	3. Problems with "C" locales : global locales, termination.
5d5e5e4e	38	</h2>
04807c28	39
5d5e5e4e	40	<p>
0214010c BK	41	The major problem is fitting an object-orientated and non-global locale
	42	design ontop of POSIX and other relevant stanards, which include the
	43	Single Unix (nee X/Open.)
04807c28	44
0214010c	45	Because POSIX falls down so completely, portibility is an issue.
64a6f971	46	</p>
0214010c	47
5d5e5e4e	48	<h2>
04807c28	49	4. Design
5d5e5e4e	50	</h2>
0214010c BK	51	Class locale in non-templatized and has three distinct types nested
	52	inside of it:
	53
	54	class facet
	55	22.1.1.1.2 Class locale::facet
	56
	57	Facets actually implement locale functionality. For instance, a facet
	58	called numpunct is the data objects that can be used to query for the
cc712abf	59	thousands separator is in the German locale.
0214010c BK	60
	61	Literally, a facet is strictly defined:
	62	- containing
	63	public:
	64	static locale::id id;
	65
	66	- or derived from another facet
	67
	68	The only other thing of interest in this class is the memory
	69	management of facets. Each constructor of a facet class takes a
	70	std::size_t __refs argument: if __refs == 0, the facet is deleted when
aa53f832 PC	71	the locale containing it is destroyed. If __refs == 1, the facet is
aa53f832 PC	72	not destroyed, even when it is no longer referenced.
0214010c BK	73
	74
	75	class id
	76	Provides an index for looking up specific facets.
04807c28	77
0214010c	78	class _Impl
aa53f832 PC	79	The internal representation of the std::locale object.
	80
	81	<h2>
	82	5. Relationship to traditional "C" locales.
	83	</h2>
	84
	85	From Josuttis, p. 697-698, which says, that "there is only one
	86	relation (of the C++ locale mechanism) to the C locale mechanism: the
	87	global C locale is modified if a named C++ locale object is set as the
	88	global locale" (emphasis Paolo), that is:
	89
	90	std::locale::global(std::locale(""));
	91
	92	affects the C functions as if the following call was made:
	93
	94	std::setlocale(LC_ALL, "");
	95
	96	On the other hand, there is no viceversa, that is, calling setlocale
	97	has no whatsoever on the C++ locale mechanism, in particular on the
	98	working of locale(""), which constructs the locale object from the
	99	environment of the running program, that is, in practice, the set of
	100	LC_ALL, LANG, etc. variable of the shell.
04807c28	101
5d5e5e4e	102	<h2>
04807c28	103	5. Examples
5d5e5e4e	104	</h2>
04807c28 BK	105
04807c28 BK	106	<pre>
0214010c	107	typedef __locale_t locale;
04807c28 BK	108	</pre>
	109
	110	More information can be found in the following testcases:
5d5e5e4e	111	<ul>
aa53f832	112	<li> testsuite/22_locale/all </li>
5d5e5e4e	113	</ul>
04807c28	114
5d5e5e4e	115	<h2>
04807c28	116	6. Unresolved Issues
5d5e5e4e	117	</h2>
04807c28	118
5d5e5e4e	119	<ul>
64a6f971	120	<li> locale -a displays available locales on linux </li>
04807c28	121
64a6f971 JW	122	<li> locale initialization: at what point does _S_classic,
	123	_S_global get initialized? Can named locales assume this
	124	initialization has already taken place? </li>
33590f13	125
64a6f971 JW	126	<li> document how named locales error check when filling data
	127	members. Ie, a fr_FR locale that doesn't have
	128	numpunct::truename(): does it use "true"? Or is it a blank
	129	string? What's the convention? </li>
33590f13	130
64a6f971 JW	131	<li> explain how locale aliasing happens. When does "de_DE"
	132	use "de" information? What is the rule for locales composed of
	133	just an ISO language code (say, "de") and locales with both an
	134	ISO language code and ISO country code (say, "de_DE"). </li>
04807c28	135
64a6f971 JW	136	<li> what should non-required facet instantiations do? If the
	137	generic implemenation is provided, then how to end-users
	138	provide specializations? </li>
e08138aa	139	</ul>
04807c28	140
5d5e5e4e	141	<h2>
04807c28	142	7. Acknowledgments
5d5e5e4e	143	</h2>
04807c28	144
5d5e5e4e	145	<h2>
04807c28	146	8. Bibliography / Referenced Documents
5d5e5e4e	147	</h2>
04807c28 BK	148
	149	Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. Character Set Handling" and "7 Locales and Internationalization"
	150
5d5e5e4e	151	<p>
04807c28	152	Drepper, Ulrich, Numerous, late-night email correspondence
64a6f971	153	</p>
04807c28	154
5d5e5e4e	155	<p>
04807c28	156	ISO/IEC 14882:1998 Programming languages - C++
64a6f971	157	</p>
04807c28	158
5d5e5e4e	159	<p>
04807c28	160	ISO/IEC 9899:1999 Programming languages - C
64a6f971	161	</p>
04807c28	162
5d5e5e4e	163	<p>
04807c28	164	Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
64a6f971	165	</p>
04807c28	166
5d5e5e4e	167	<p>
04807c28	168	Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
64a6f971	169	</p>
04807c28	170
5d5e5e4e	171	<p>
04807c28 BK	172	System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
	173	The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
	174	http://www.opennc.org/austin/docreg.html
64a6f971 JW	175	</p>
	176
	177	</body>
	178	</html>
	179
	180