xref: /aoo42x/main/sal/inc/rtl/locale.hxx (revision 24c56ab9)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_LOCALE_HXX_
25 #define _RTL_LOCALE_HXX_
26 
27 #include <rtl/locale.h>
28 #include <rtl/ustring.hxx>
29 
30 #ifdef __cplusplus
31 
32 namespace rtl
33 {
34 
35 /**
36 	A <code>OLocale</code> object represents a specific geographical, political,
37 	or cultural region. An operation that requires a <code>OLocale</code> to perform
38 	its task is called <em>locale-sensitive</em> and uses the <code>OLocale</code>
39 	to tailor information for the user. For example, displaying a number
40 	is a locale-sensitive operation--the number should be formatted
41 	according to the customs/conventions of the user's native country,
42 	region, or culture.
43 
44 	<P>
45 	You create a <code>OLocale</code> object using one of the two constructors in
46 	this class:
47 	<blockquote>
48 	<pre>
49 	OLocale(String language, String country)
50 	OLocale(String language, String country, String variant)
51 	</pre>
52 	</blockquote>
53 	The first argument to both constructors is a valid <STRONG>ISO
54 	Language Code.</STRONG> These codes are the lower-case two-letter
55 	codes as defined by ISO-639.
56 	You can find a full list of these codes at a number of sites, such as:
57 	<BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
58 	<code>http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</code></a>
59 
60 	<P>
61 	The second argument to both constructors is a valid <STRONG>ISO Country
62 	Code.</STRONG> These codes are the upper-case two-letter codes
63 	as defined by ISO-3166.
64 	You can find a full list of these codes at a number of sites, such as:
65 	<BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
66 	<code>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</code></a>
67 
68 	<P>
69 	The second constructor requires a third argument--the <STRONG>Variant.</STRONG>
70 	The Variant codes are vendor and browser-specific.
71 	For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
72 	Where there are two variants, separate them with an underscore, and
73 	put the most important one first. For
74 	example, a Traditional Spanish collation might be referenced, with
75 	"ES", "ES", "Traditional_WIN".
76 
77 	<P>
78 	Because a <code>OLocale</code> object is just an identifier for a region,
79 	no validity check is performed when you construct a <code>OLocale</code>.
80 	If you want to see whether particular resources are available for the
81 	<code>OLocale</code> you construct, you must query those resources. For
82 	example, ask the <code>NumberFormat</code> for the locales it supports
83 	using its <code>getAvailableLocales</code> method.
84 	<BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
85 	locale, you get back the best available match, not necessarily
86 	precisely what you asked for. For more information, look at
87 	<a href="java.util.ResourceBundle.html"><code>ResourceBundle</code></a>.
88 
89 	<P>
90 	The <code>OLocale</code> class provides a number of convenient constants
91 	that you can use to create <code>OLocale</code> objects for commonly used
92 	locales. For example, the following creates a <code>OLocale</code> object
93 	for the United States:
94 	<blockquote>
95 	<pre>
96 	OLocale.US
97 	</pre>
98 	</blockquote>
99 
100 	<P>
101 	Once you've created a <code>OLocale</code> you can query it for information about
102 	itself. Use <code>getCountry</code> to get the ISO Country Code and
103 	<code>getLanguage</code> to get the ISO Language Code. You can
104 	use <code>getDisplayCountry</code> to get the
105 	name of the country suitable for displaying to the user. Similarly,
106 	you can use <code>getDisplayLanguage</code> to get the name of
107 	the language suitable for displaying to the user. Interestingly,
108 	the <code>getDisplayXXX</code> methods are themselves locale-sensitive
109 	and have two versions: one that uses the default locale and one
110 	that uses the locale specified as an argument.
111 
112 	<P>
113 	The JDK provides a number of classes that perform locale-sensitive
114 	operations. For example, the <code>NumberFormat</code> class formats
115 	numbers, currency, or percentages in a locale-sensitive manner. Classes
116 	such as <code>NumberFormat</code> have a number of convenience methods
117 	for creating a default object of that type. For example, the
118 	<code>NumberFormat</code> class provides these three convenience methods
119 	for creating a default <code>NumberFormat</code> object:
120 	<blockquote>
121 	<pre>
122 	NumberFormat.getInstance()
123 	NumberFormat.getCurrencyInstance()
124 	NumberFormat.getPercentInstance()
125 	</pre>
126 	</blockquote>
127 	These methods have two variants; one with an explicit locale
128 	and one without; the latter using the default locale.
129 	<blockquote>
130 	<pre>
131 	NumberFormat.getInstance(myLocale)
132 	NumberFormat.getCurrencyInstance(myLocale)
133 	NumberFormat.getPercentInstance(myLocale)
134 	</pre>
135 	</blockquote>
136 	A <code>OLocale</code> is the mechanism for identifying the kind of object
137 	(<code>NumberFormat</code>) that you would like to get. The locale is
138 	<STRONG>just</STRONG> a mechanism for identifying objects,
139 	<STRONG>not</STRONG> a container for the objects themselves.
140 
141 	<P>
142 	Each class that performs locale-sensitive operations allows you
143 	to get all the available objects of that type. You can sift
144 	through these objects by language, country, or variant,
145 	and use the display names to present a menu to the user.
146 	For example, you can create a menu of all the collation objects
147 	suitable for a given language. Such classes must implement these
148 	three class methods:
149 	<blockquote>
150 	<pre>
151 	public static OLocale[] getAvailableLocales()
152 	public static String getDisplayName(OLocale objectLocale,
153 									   OLocale displayLocale)
154 	public static final String getDisplayName(OLocale objectLocale)
155 	   // getDisplayName will throw MissingResourceException if the locale
156 	   // is not one of the available locales.
157 	</pre>
158 	</blockquote>
159  */
160 class OLocale
161 {
162 public:
OLocale(rtl_Locale * locale)163 	OLocale( rtl_Locale * locale )
164 		: pData( locale ) {}
165 
OLocale(const OLocale & obj)166 	OLocale( const OLocale & obj)
167 		: pData(obj.pData) {}
168 
operator =(const OLocale & obj)169 	OLocale & operator = ( const OLocale & obj)
170 		{
171 			pData = obj.pData;
172 			return *this;
173 		}
174 
175 	/**
176 	 	Construct a locale from language, country, variant.
177 		@param language lowercase two-letter ISO-639 code.
178 		@param country uppercase two-letter ISO-3166 code.
179 		@param variant vendor and browser specific code. See class description.
180 	 */
registerLocale(const OUString & language,const OUString & country,const OUString & variant)181 	static OLocale registerLocale( const OUString & language, const OUString & country,
182 							const OUString & variant )
183 	{
184 		return rtl_locale_register( language.getStr(), country.getStr(), variant.getStr() );
185 	}
186 
187 	/**
188 	 	Construct a locale from language, country.
189 		@param language lowercase two-letter ISO-639 code.
190 		@param country uppercase two-letter ISO-3166 code.
191 	 */
registerLocale(const OUString & language,const OUString & country)192 	static OLocale registerLocale( const OUString & language, const OUString & country )
193 	{
194 		return rtl_locale_register( language.getStr(), country.getStr(), NULL );
195 	}
196 
197 	/** @deprecated
198 	 */
getDefault()199 	static OLocale getDefault()  { return rtl_locale_getDefault(); }
200 
201 	/** @deprecated
202 	 */
setDefault(const OUString & language,const OUString & country,const OUString & variant)203 	static void setDefault( const OUString & language, const OUString & country,
204 							const OUString & variant )
205 			 { rtl_locale_setDefault( language.getStr(), country.getStr(), variant.getStr()); }
206 
207 	/**
208 	 	Getter for programmatic name of field,
209 	 	an lowercased two-letter ISO-639 code.
210 	 */
getLanguage() const211 	OUString getLanguage() const { return pData->Language; }
212 
213 	/**
214 	 	Getter for programmatic name of field,
215 	 	an uppercased two-letter ISO-3166 code.
216 	 */
getCountry() const217 	OUString getCountry() const { return pData->Country; }
218 
219 	/**
220 	 	Getter for programmatic name of field.
221 	 */
getVariant() const222 	OUString getVariant() const { return pData->Variant; }
223 
224 
225 	/**
226 	 	Returns the hash code of the locale This.
227 	 */
hashCode() const228 	sal_Int32 hashCode() const { return pData->HashCode; }
229 
operator ==(const OLocale & obj) const230 	sal_Bool operator == (const OLocale & obj ) const
231 	{
232 		return pData == obj.pData;
233 	}
234 
getData() const235 	rtl_Locale *	getData() const { return pData; }
236 
237 private:
238 	/**
239 	 	Must be the first member in this class. OUString access this member with
240 	 	*(rtl_Locale **)&locale.
241 	 */
242 	rtl_Locale *	pData;
243 
OLocale()244 	OLocale()
245 		: pData(rtl_locale_getDefault()) {}
246 /*
247 	OLocale( const OLocale & obj)
248 		: pData(obj.pData) {}
249 
250 	OLocale & operator = ( const OLocale & obj)
251 		{ pData = obj.pData;
252 		  return *this;
253 		}
254 */
255 };
256 
257 }
258 
259 #endif /* __cplusplus */
260 #endif /* _RTL_LOCALE_HXX_ */
261 
262 
263