1/*
2 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Axel Dörfler, axeld@pinc-software.de.
7 *		John Scipione, jscipione@gmail.com
8 *		Oliver Tappe, zooey@hirschkaefer.de.
9 *
10 * Corresponds to:
11 *		headers/os/locale/Locale.h	hrev48439
12 *		src/kits/locale/Locale.cpp	hrev48439
13 */
14
15
16/*!
17	\file Locale.h
18	\ingroup locale
19	\ingroup libbe
20	\brief Provides the BLocale class, the base class of the Locale Kit.
21*/
22
23
24/*!
25	\class BLocale
26	\ingroup locale
27	\ingroup libbe
28	\brief Class for representing a locale and its settings.
29
30	A locale is defined by the combination of a country and a language.
31	Using these two informations, it is possible to determine the format
32	to use for date, time, and number formatting. The BLocale class also
33	provide collators, which allows you to sort a list of strings properly
34	depending on a set of rules about accented chars and other special
35	cases that vary over the different locales.
36
37	BLocale is also the class to use when you want to perform formatting
38	or parsing of dates, times, and numbers, in the natural language of
39	the user.
40
41	\since Haiku R1
42*/
43
44
45/*!
46	\fn BLocale::BLocale(const BLanguage* language,
47		const BFormattingConventions* conventions)
48	\brief Initializes a BLocale object corresponding to the passed in
49	       \a language and \a conventions.
50
51	\since Haiku R1
52*/
53
54
55/*!
56	\fn BLocale::BLocale(const BLocale& other)
57	\brief Initializes a BLocale object as a copy of \a other.
58
59	\param other The BLocale object to initialize from.
60
61	\since Haiku R1
62*/
63
64
65/*!
66	status_t BLocale::GetCollator(BCollator* collator) const
67	\brief Gets the collator associated to this locale.
68
69	Returns the collator in use for this locale, allowing you to use it
70	to sort a set of strings.
71
72	\since Haiku R1
73*/
74
75
76/*!
77	\fn BLocale& BLocale::operator=(const BLocale& other)
78	\brief Initializes a BLocale object as a copy of \a other by overloading
79	       the = operator.
80
81	\param other The BLocale object to initialize from.
82
83	\since Haiku R1
84*/
85
86
87/*!
88	\fn BLocale::~BLocale()
89	\brief Destructor method.
90
91	\since Haiku R1
92*/
93
94
95/*!
96	\fn status_t BLocale::GetCollator(BCollator* collator) const
97	\brief Sets \a collator object to the default collator for the BLocale.
98
99	\param collator A pointer to a BCollator object to fill out.
100
101	\returns A status code.
102	\retval B_OK Everything went well.
103	\retval B_BAD_VALUE \c NULL \a collator object passed in.
104	\retval B_ERROR Unable to lock the BLocale.
105
106	\since Haiku R1
107*/
108
109
110/*!
111	\fn status_t BLocale::GetLanguage(BLanguage* language) const
112	\brief Sets \a language object to the default language for the BLocale.
113
114	\param language A pointer to a BLanguage object to fill out.
115
116	\returns A status code.
117	\retval B_OK Everything went well.
118	\retval B_BAD_VALUE \c NULL \a language object passed in.
119	\retval B_ERROR Unable to lock the BLocale.
120
121	\since Haiku R1
122*/
123
124
125/*!
126	\fn status_t BLocale::GetFormattingConventions(
127		BFormattingConventions* conventions) const
128	\brief Fills out \a conventions with the default formatting conventions
129	       for the BLocale.
130
131	\param conventions A pointer to a BFormattingConventions object to fill
132	       out.
133
134	\returns A status code.
135	\retval B_OK Everything went well.
136	\retval B_BAD_VALUE \c NULL \a conventions object passed in.
137	\retval B_ERROR Unable to lock the BLocale.
138
139	\since Haiku R1
140*/
141
142
143/*!
144	\fn const char* BLocale::GetString(uint32 id) const
145	\brief Gets the language string for the locale.
146
147	\param id The locale \a id to get the language of.
148
149	\internal Assumes a certain order of the string bases.
150
151	\returns A blank string in the case of an error or the string "UTF-8"
152	         if there is \a id is set to \a B_CODESET.
153
154	\since Haiku R1
155*/
156
157
158/*!
159	\fn void BLocale::SetFormattingConventions(
160		const BFormattingConventions& conventions)
161	\brief Sets the formatting convention for this locale.
162
163	If unable to lock the BLocale \a conventions is left untouched.
164
165	\param conventions The formatting convention to set.
166
167	\since Haiku R1
168*/
169
170
171/*!
172	\fn void BLocale::SetCollator(const BCollator& newCollator)
173	\brief Set the collator for this locale.
174
175	If unable to lock the BLocale \a newCollator is left untouched.
176
177	\param newCollator The collator to set.
178
179	\since Haiku R1
180*/
181
182
183/*!
184	\fn void BLocale::SetLanguage(const BLanguage& newLanguage)
185	\brief Set the language for this locale.
186
187	If unable to lock the BLocale \a newLanguage is left untouched.
188
189	\param newLanguage The code of the language to set to locale to.
190
191	\since Haiku R1
192*/
193