Line data Source code
1 : // © 2016 and later: Unicode, Inc. and others.
2 : // License & terms of use: http://www.unicode.org/copyright.html
3 : /*
4 : ******************************************************************************
5 : *
6 : * Copyright (C) 1996-2015, International Business Machines
7 : * Corporation and others. All Rights Reserved.
8 : *
9 : ******************************************************************************
10 : *
11 : * File locid.h
12 : *
13 : * Created by: Helena Shih
14 : *
15 : * Modification History:
16 : *
17 : * Date Name Description
18 : * 02/11/97 aliu Changed gLocPath to fgLocPath and added methods to
19 : * get and set it.
20 : * 04/02/97 aliu Made operator!= inline; fixed return value of getName().
21 : * 04/15/97 aliu Cleanup for AIX/Win32.
22 : * 04/24/97 aliu Numerous changes per code review.
23 : * 08/18/98 stephen Added tokenizeString(),changed getDisplayName()
24 : * 09/08/98 stephen Moved definition of kEmptyString for Mac Port
25 : * 11/09/99 weiv Added const char * getName() const;
26 : * 04/12/00 srl removing unicodestring api's and cached hash code
27 : * 08/10/01 grhoten Change the static Locales to accessor functions
28 : ******************************************************************************
29 : */
30 :
31 : #ifndef LOCID_H
32 : #define LOCID_H
33 :
34 : #include "unicode/utypes.h"
35 : #include "unicode/uobject.h"
36 : #include "unicode/putil.h"
37 : #include "unicode/uloc.h"
38 :
39 : /**
40 : * \file
41 : * \brief C++ API: Locale ID object.
42 : */
43 :
44 : U_NAMESPACE_BEGIN
45 :
46 : // Forward Declarations
47 : void U_CALLCONV locale_available_init(); /**< @internal */
48 :
49 : class StringEnumeration;
50 : class UnicodeString;
51 :
52 : /**
53 : * A <code>Locale</code> object represents a specific geographical, political,
54 : * or cultural region. An operation that requires a <code>Locale</code> to perform
55 : * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
56 : * to tailor information for the user. For example, displaying a number
57 : * is a locale-sensitive operation--the number should be formatted
58 : * according to the customs/conventions of the user's native country,
59 : * region, or culture.
60 : *
61 : * The Locale class is not suitable for subclassing.
62 : *
63 : * <P>
64 : * You can create a <code>Locale</code> object using the constructor in
65 : * this class:
66 : * \htmlonly<blockquote>\endhtmlonly
67 : * <pre>
68 : * Locale( const char* language,
69 : * const char* country,
70 : * const char* variant);
71 : * </pre>
72 : * \htmlonly</blockquote>\endhtmlonly
73 : * The first argument to the constructors is a valid <STRONG>ISO
74 : * Language Code.</STRONG> These codes are the lower-case two-letter
75 : * codes as defined by ISO-639.
76 : * You can find a full list of these codes at:
77 : * <BR><a href ="http://www.loc.gov/standards/iso639-2/">
78 : * http://www.loc.gov/standards/iso639-2/</a>
79 : *
80 : * <P>
81 : * The second argument to the constructors is a valid <STRONG>ISO Country
82 : * Code.</STRONG> These codes are the upper-case two-letter codes
83 : * as defined by ISO-3166.
84 : * You can find a full list of these codes at a number of sites, such as:
85 : * <BR><a href="http://www.iso.org/iso/en/prods-services/iso3166ma/index.html">
86 : * http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</a>
87 : *
88 : * <P>
89 : * The third constructor requires a third argument--the <STRONG>Variant.</STRONG>
90 : * The Variant codes are vendor and browser-specific.
91 : * For example, use REVISED for a langauge's revised script orthography, and POSIX for POSIX.
92 : * Where there are two variants, separate them with an underscore, and
93 : * put the most important one first. For
94 : * example, a Traditional Spanish collation might be referenced, with
95 : * "ES", "ES", "Traditional_POSIX".
96 : *
97 : * <P>
98 : * Because a <code>Locale</code> object is just an identifier for a region,
99 : * no validity check is performed when you construct a <code>Locale</code>.
100 : * If you want to see whether particular resources are available for the
101 : * <code>Locale</code> you construct, you must query those resources. For
102 : * example, ask the <code>NumberFormat</code> for the locales it supports
103 : * using its <code>getAvailableLocales</code> method.
104 : * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
105 : * locale, you get back the best available match, not necessarily
106 : * precisely what you asked for. For more information, look at
107 : * <code>ResourceBundle</code>.
108 : *
109 : * <P>
110 : * The <code>Locale</code> class provides a number of convenient constants
111 : * that you can use to create <code>Locale</code> objects for commonly used
112 : * locales. For example, the following refers to a <code>Locale</code> object
113 : * for the United States:
114 : * \htmlonly<blockquote>\endhtmlonly
115 : * <pre>
116 : * Locale::getUS()
117 : * </pre>
118 : * \htmlonly</blockquote>\endhtmlonly
119 : *
120 : * <P>
121 : * Once you've created a <code>Locale</code> you can query it for information about
122 : * itself. Use <code>getCountry</code> to get the ISO Country Code and
123 : * <code>getLanguage</code> to get the ISO Language Code. You can
124 : * use <code>getDisplayCountry</code> to get the
125 : * name of the country suitable for displaying to the user. Similarly,
126 : * you can use <code>getDisplayLanguage</code> to get the name of
127 : * the language suitable for displaying to the user. Interestingly,
128 : * the <code>getDisplayXXX</code> methods are themselves locale-sensitive
129 : * and have two versions: one that uses the default locale and one
130 : * that takes a locale as an argument and displays the name or country in
131 : * a language appropriate to that locale.
132 : *
133 : * <P>
134 : * ICU provides a number of classes that perform locale-sensitive
135 : * operations. For example, the <code>NumberFormat</code> class formats
136 : * numbers, currency, or percentages in a locale-sensitive manner. Classes
137 : * such as <code>NumberFormat</code> have a number of convenience methods
138 : * for creating a default object of that type. For example, the
139 : * <code>NumberFormat</code> class provides these three convenience methods
140 : * for creating a default <code>NumberFormat</code> object:
141 : * \htmlonly<blockquote>\endhtmlonly
142 : * <pre>
143 : * UErrorCode success = U_ZERO_ERROR;
144 : * Locale myLocale;
145 : * NumberFormat *nf;
146 : *
147 : * nf = NumberFormat::createInstance( success ); delete nf;
148 : * nf = NumberFormat::createCurrencyInstance( success ); delete nf;
149 : * nf = NumberFormat::createPercentInstance( success ); delete nf;
150 : * </pre>
151 : * \htmlonly</blockquote>\endhtmlonly
152 : * Each of these methods has two variants; one with an explicit locale
153 : * and one without; the latter using the default locale.
154 : * \htmlonly<blockquote>\endhtmlonly
155 : * <pre>
156 : * nf = NumberFormat::createInstance( myLocale, success ); delete nf;
157 : * nf = NumberFormat::createCurrencyInstance( myLocale, success ); delete nf;
158 : * nf = NumberFormat::createPercentInstance( myLocale, success ); delete nf;
159 : * </pre>
160 : * \htmlonly</blockquote>\endhtmlonly
161 : * A <code>Locale</code> is the mechanism for identifying the kind of object
162 : * (<code>NumberFormat</code>) that you would like to get. The locale is
163 : * <STRONG>just</STRONG> a mechanism for identifying objects,
164 : * <STRONG>not</STRONG> a container for the objects themselves.
165 : *
166 : * <P>
167 : * Each class that performs locale-sensitive operations allows you
168 : * to get all the available objects of that type. You can sift
169 : * through these objects by language, country, or variant,
170 : * and use the display names to present a menu to the user.
171 : * For example, you can create a menu of all the collation objects
172 : * suitable for a given language. Such classes implement these
173 : * three class methods:
174 : * \htmlonly<blockquote>\endhtmlonly
175 : * <pre>
176 : * static Locale* getAvailableLocales(int32_t& numLocales)
177 : * static UnicodeString& getDisplayName(const Locale& objectLocale,
178 : * const Locale& displayLocale,
179 : * UnicodeString& displayName)
180 : * static UnicodeString& getDisplayName(const Locale& objectLocale,
181 : * UnicodeString& displayName)
182 : * </pre>
183 : * \htmlonly</blockquote>\endhtmlonly
184 : *
185 : * @stable ICU 2.0
186 : * @see ResourceBundle
187 : */
188 : class U_COMMON_API Locale : public UObject {
189 : public:
190 : /** Useful constant for the Root locale. @stable ICU 4.4 */
191 : static const Locale &U_EXPORT2 getRoot(void);
192 : /** Useful constant for this language. @stable ICU 2.0 */
193 : static const Locale &U_EXPORT2 getEnglish(void);
194 : /** Useful constant for this language. @stable ICU 2.0 */
195 : static const Locale &U_EXPORT2 getFrench(void);
196 : /** Useful constant for this language. @stable ICU 2.0 */
197 : static const Locale &U_EXPORT2 getGerman(void);
198 : /** Useful constant for this language. @stable ICU 2.0 */
199 : static const Locale &U_EXPORT2 getItalian(void);
200 : /** Useful constant for this language. @stable ICU 2.0 */
201 : static const Locale &U_EXPORT2 getJapanese(void);
202 : /** Useful constant for this language. @stable ICU 2.0 */
203 : static const Locale &U_EXPORT2 getKorean(void);
204 : /** Useful constant for this language. @stable ICU 2.0 */
205 : static const Locale &U_EXPORT2 getChinese(void);
206 : /** Useful constant for this language. @stable ICU 2.0 */
207 : static const Locale &U_EXPORT2 getSimplifiedChinese(void);
208 : /** Useful constant for this language. @stable ICU 2.0 */
209 : static const Locale &U_EXPORT2 getTraditionalChinese(void);
210 :
211 : /** Useful constant for this country/region. @stable ICU 2.0 */
212 : static const Locale &U_EXPORT2 getFrance(void);
213 : /** Useful constant for this country/region. @stable ICU 2.0 */
214 : static const Locale &U_EXPORT2 getGermany(void);
215 : /** Useful constant for this country/region. @stable ICU 2.0 */
216 : static const Locale &U_EXPORT2 getItaly(void);
217 : /** Useful constant for this country/region. @stable ICU 2.0 */
218 : static const Locale &U_EXPORT2 getJapan(void);
219 : /** Useful constant for this country/region. @stable ICU 2.0 */
220 : static const Locale &U_EXPORT2 getKorea(void);
221 : /** Useful constant for this country/region. @stable ICU 2.0 */
222 : static const Locale &U_EXPORT2 getChina(void);
223 : /** Useful constant for this country/region. @stable ICU 2.0 */
224 : static const Locale &U_EXPORT2 getPRC(void);
225 : /** Useful constant for this country/region. @stable ICU 2.0 */
226 : static const Locale &U_EXPORT2 getTaiwan(void);
227 : /** Useful constant for this country/region. @stable ICU 2.0 */
228 : static const Locale &U_EXPORT2 getUK(void);
229 : /** Useful constant for this country/region. @stable ICU 2.0 */
230 : static const Locale &U_EXPORT2 getUS(void);
231 : /** Useful constant for this country/region. @stable ICU 2.0 */
232 : static const Locale &U_EXPORT2 getCanada(void);
233 : /** Useful constant for this country/region. @stable ICU 2.0 */
234 : static const Locale &U_EXPORT2 getCanadaFrench(void);
235 :
236 :
237 : /**
238 : * Construct a default locale object, a Locale for the default locale ID.
239 : *
240 : * @see getDefault
241 : * @see uloc_getDefault
242 : * @stable ICU 2.0
243 : */
244 : Locale();
245 :
246 : /**
247 : * Construct a locale from language, country, variant.
248 : * If an error occurs, then the constructed object will be "bogus"
249 : * (isBogus() will return TRUE).
250 : *
251 : * @param language Lowercase two-letter or three-letter ISO-639 code.
252 : * This parameter can instead be an ICU style C locale (e.g. "en_US"),
253 : * but the other parameters must not be used.
254 : * This parameter can be NULL; if so,
255 : * the locale is initialized to match the current default locale.
256 : * (This is the same as using the default constructor.)
257 : * Please note: The Java Locale class does NOT accept the form
258 : * 'new Locale("en_US")' but only 'new Locale("en","US")'
259 : *
260 : * @param country Uppercase two-letter ISO-3166 code. (optional)
261 : * @param variant Uppercase vendor and browser specific code. See class
262 : * description. (optional)
263 : * @param keywordsAndValues A string consisting of keyword/values pairs, such as
264 : * "collation=phonebook;currency=euro"
265 : *
266 : * @see getDefault
267 : * @see uloc_getDefault
268 : * @stable ICU 2.0
269 : */
270 : Locale( const char * language,
271 : const char * country = 0,
272 : const char * variant = 0,
273 : const char * keywordsAndValues = 0);
274 :
275 : /**
276 : * Initializes a Locale object from another Locale object.
277 : *
278 : * @param other The Locale object being copied in.
279 : * @stable ICU 2.0
280 : */
281 : Locale(const Locale& other);
282 :
283 :
284 : /**
285 : * Destructor
286 : * @stable ICU 2.0
287 : */
288 : virtual ~Locale() ;
289 :
290 : /**
291 : * Replaces the entire contents of *this with the specified value.
292 : *
293 : * @param other The Locale object being copied in.
294 : * @return *this
295 : * @stable ICU 2.0
296 : */
297 : Locale& operator=(const Locale& other);
298 :
299 : /**
300 : * Checks if two locale keys are the same.
301 : *
302 : * @param other The locale key object to be compared with this.
303 : * @return True if the two locale keys are the same, false otherwise.
304 : * @stable ICU 2.0
305 : */
306 : UBool operator==(const Locale& other) const;
307 :
308 : /**
309 : * Checks if two locale keys are not the same.
310 : *
311 : * @param other The locale key object to be compared with this.
312 : * @return True if the two locale keys are not the same, false
313 : * otherwise.
314 : * @stable ICU 2.0
315 : */
316 : UBool operator!=(const Locale& other) const;
317 :
318 : /**
319 : * Clone this object.
320 : * Clones can be used concurrently in multiple threads.
321 : * If an error occurs, then NULL is returned.
322 : * The caller must delete the clone.
323 : *
324 : * @return a clone of this object
325 : *
326 : * @see getDynamicClassID
327 : * @stable ICU 2.8
328 : */
329 : Locale *clone() const;
330 :
331 : #ifndef U_HIDE_SYSTEM_API
332 : /**
333 : * Common methods of getting the current default Locale. Used for the
334 : * presentation: menus, dialogs, etc. Generally set once when your applet or
335 : * application is initialized, then never reset. (If you do reset the
336 : * default locale, you probably want to reload your GUI, so that the change
337 : * is reflected in your interface.)
338 : *
339 : * More advanced programs will allow users to use different locales for
340 : * different fields, e.g. in a spreadsheet.
341 : *
342 : * Note that the initial setting will match the host system.
343 : * @return a reference to the Locale object for the default locale ID
344 : * @system
345 : * @stable ICU 2.0
346 : */
347 : static const Locale& U_EXPORT2 getDefault(void);
348 :
349 : /**
350 : * Sets the default. Normally set once at the beginning of a process,
351 : * then never reset.
352 : * setDefault() only changes ICU's default locale ID, <strong>not</strong>
353 : * the default locale ID of the runtime environment.
354 : *
355 : * @param newLocale Locale to set to. If NULL, set to the value obtained
356 : * from the runtime environement.
357 : * @param success The error code.
358 : * @system
359 : * @stable ICU 2.0
360 : */
361 : static void U_EXPORT2 setDefault(const Locale& newLocale,
362 : UErrorCode& success);
363 : #endif /* U_HIDE_SYSTEM_API */
364 :
365 : /**
366 : * Creates a locale which has had minimal canonicalization
367 : * as per uloc_getName().
368 : * @param name The name to create from. If name is null,
369 : * the default Locale is used.
370 : * @return new locale object
371 : * @stable ICU 2.0
372 : * @see uloc_getName
373 : */
374 : static Locale U_EXPORT2 createFromName(const char *name);
375 :
376 : /**
377 : * Creates a locale from the given string after canonicalizing
378 : * the string by calling uloc_canonicalize().
379 : * @param name the locale ID to create from. Must not be NULL.
380 : * @return a new locale object corresponding to the given name
381 : * @stable ICU 3.0
382 : * @see uloc_canonicalize
383 : */
384 : static Locale U_EXPORT2 createCanonical(const char* name);
385 :
386 : /**
387 : * Returns the locale's ISO-639 language code.
388 : * @return An alias to the code
389 : * @stable ICU 2.0
390 : */
391 : inline const char * getLanguage( ) const;
392 :
393 : /**
394 : * Returns the locale's ISO-15924 abbreviation script code.
395 : * @return An alias to the code
396 : * @see uscript_getShortName
397 : * @see uscript_getCode
398 : * @stable ICU 2.8
399 : */
400 : inline const char * getScript( ) const;
401 :
402 : /**
403 : * Returns the locale's ISO-3166 country code.
404 : * @return An alias to the code
405 : * @stable ICU 2.0
406 : */
407 : inline const char * getCountry( ) const;
408 :
409 : /**
410 : * Returns the locale's variant code.
411 : * @return An alias to the code
412 : * @stable ICU 2.0
413 : */
414 : inline const char * getVariant( ) const;
415 :
416 : /**
417 : * Returns the programmatic name of the entire locale, with the language,
418 : * country and variant separated by underbars. If a field is missing, up
419 : * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
420 : * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
421 : * @return A pointer to "name".
422 : * @stable ICU 2.0
423 : */
424 : inline const char * getName() const;
425 :
426 : /**
427 : * Returns the programmatic name of the entire locale as getName() would return,
428 : * but without keywords.
429 : * @return A pointer to "name".
430 : * @see getName
431 : * @stable ICU 2.8
432 : */
433 : const char * getBaseName() const;
434 :
435 :
436 : /**
437 : * Gets the list of keywords for the specified locale.
438 : *
439 : * @param status the status code
440 : * @return pointer to StringEnumeration class, or NULL if there are no keywords.
441 : * Client must dispose of it by calling delete.
442 : * @stable ICU 2.8
443 : */
444 : StringEnumeration * createKeywords(UErrorCode &status) const;
445 :
446 : /**
447 : * Gets the value for a keyword.
448 : *
449 : * @param keywordName name of the keyword for which we want the value. Case insensitive.
450 : * @param buffer The buffer to receive the keyword value.
451 : * @param bufferCapacity The capacity of receiving buffer
452 : * @param status Returns any error information while performing this operation.
453 : * @return the length of the keyword value
454 : *
455 : * @stable ICU 2.8
456 : */
457 : int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
458 :
459 : /**
460 : * Sets or removes the value for a keyword.
461 : *
462 : * For removing all keywords, use getBaseName(),
463 : * and construct a new Locale if it differs from getName().
464 : *
465 : * @param keywordName name of the keyword to be set. Case insensitive.
466 : * @param keywordValue value of the keyword to be set. If 0-length or
467 : * NULL, will result in the keyword being removed. No error is given if
468 : * that keyword does not exist.
469 : * @param status Returns any error information while performing this operation.
470 : *
471 : * @stable ICU 49
472 : */
473 : void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
474 :
475 : /**
476 : * returns the locale's three-letter language code, as specified
477 : * in ISO draft standard ISO-639-2.
478 : * @return An alias to the code, or an empty string
479 : * @stable ICU 2.0
480 : */
481 : const char * getISO3Language() const;
482 :
483 : /**
484 : * Fills in "name" with the locale's three-letter ISO-3166 country code.
485 : * @return An alias to the code, or an empty string
486 : * @stable ICU 2.0
487 : */
488 : const char * getISO3Country() const;
489 :
490 : /**
491 : * Returns the Windows LCID value corresponding to this locale.
492 : * This value is stored in the resource data for the locale as a one-to-four-digit
493 : * hexadecimal number. If the resource is missing, in the wrong format, or
494 : * there is no Windows LCID value that corresponds to this locale, returns 0.
495 : * @stable ICU 2.0
496 : */
497 : uint32_t getLCID(void) const;
498 :
499 : /**
500 : * Returns whether this locale's script is written right-to-left.
501 : * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
502 : * If no likely script is known, then FALSE is returned.
503 : *
504 : * A script is right-to-left according to the CLDR script metadata
505 : * which corresponds to whether the script's letters have Bidi_Class=R or AL.
506 : *
507 : * Returns TRUE for "ar" and "en-Hebr", FALSE for "zh" and "fa-Cyrl".
508 : *
509 : * @return TRUE if the locale's script is written right-to-left
510 : * @stable ICU 54
511 : */
512 : UBool isRightToLeft() const;
513 :
514 : /**
515 : * Fills in "dispLang" with the name of this locale's language in a format suitable for
516 : * user display in the default locale. For example, if the locale's language code is
517 : * "fr" and the default locale's language code is "en", this function would set
518 : * dispLang to "French".
519 : * @param dispLang Receives the language's display name.
520 : * @return A reference to "dispLang".
521 : * @stable ICU 2.0
522 : */
523 : UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
524 :
525 : /**
526 : * Fills in "dispLang" with the name of this locale's language in a format suitable for
527 : * user display in the locale specified by "displayLocale". For example, if the locale's
528 : * language code is "en" and displayLocale's language code is "fr", this function would set
529 : * dispLang to "Anglais".
530 : * @param displayLocale Specifies the locale to be used to display the name. In other words,
531 : * if the locale's language code is "en", passing Locale::getFrench() for
532 : * displayLocale would result in "Anglais", while passing Locale::getGerman()
533 : * for displayLocale would result in "Englisch".
534 : * @param dispLang Receives the language's display name.
535 : * @return A reference to "dispLang".
536 : * @stable ICU 2.0
537 : */
538 : UnicodeString& getDisplayLanguage( const Locale& displayLocale,
539 : UnicodeString& dispLang) const;
540 :
541 : /**
542 : * Fills in "dispScript" with the name of this locale's script in a format suitable
543 : * for user display in the default locale. For example, if the locale's script code
544 : * is "LATN" and the default locale's language code is "en", this function would set
545 : * dispScript to "Latin".
546 : * @param dispScript Receives the scripts's display name.
547 : * @return A reference to "dispScript".
548 : * @stable ICU 2.8
549 : */
550 : UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
551 :
552 : /**
553 : * Fills in "dispScript" with the name of this locale's country in a format suitable
554 : * for user display in the locale specified by "displayLocale". For example, if the locale's
555 : * script code is "LATN" and displayLocale's language code is "en", this function would set
556 : * dispScript to "Latin".
557 : * @param displayLocale Specifies the locale to be used to display the name. In other
558 : * words, if the locale's script code is "LATN", passing
559 : * Locale::getFrench() for displayLocale would result in "", while
560 : * passing Locale::getGerman() for displayLocale would result in
561 : * "".
562 : * @param dispScript Receives the scripts's display name.
563 : * @return A reference to "dispScript".
564 : * @stable ICU 2.8
565 : */
566 : UnicodeString& getDisplayScript( const Locale& displayLocale,
567 : UnicodeString& dispScript) const;
568 :
569 : /**
570 : * Fills in "dispCountry" with the name of this locale's country in a format suitable
571 : * for user display in the default locale. For example, if the locale's country code
572 : * is "FR" and the default locale's language code is "en", this function would set
573 : * dispCountry to "France".
574 : * @param dispCountry Receives the country's display name.
575 : * @return A reference to "dispCountry".
576 : * @stable ICU 2.0
577 : */
578 : UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
579 :
580 : /**
581 : * Fills in "dispCountry" with the name of this locale's country in a format suitable
582 : * for user display in the locale specified by "displayLocale". For example, if the locale's
583 : * country code is "US" and displayLocale's language code is "fr", this function would set
584 : * dispCountry to "États-Unis".
585 : * @param displayLocale Specifies the locale to be used to display the name. In other
586 : * words, if the locale's country code is "US", passing
587 : * Locale::getFrench() for displayLocale would result in "États-Unis", while
588 : * passing Locale::getGerman() for displayLocale would result in
589 : * "Vereinigte Staaten".
590 : * @param dispCountry Receives the country's display name.
591 : * @return A reference to "dispCountry".
592 : * @stable ICU 2.0
593 : */
594 : UnicodeString& getDisplayCountry( const Locale& displayLocale,
595 : UnicodeString& dispCountry) const;
596 :
597 : /**
598 : * Fills in "dispVar" with the name of this locale's variant code in a format suitable
599 : * for user display in the default locale.
600 : * @param dispVar Receives the variant's name.
601 : * @return A reference to "dispVar".
602 : * @stable ICU 2.0
603 : */
604 : UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
605 :
606 : /**
607 : * Fills in "dispVar" with the name of this locale's variant code in a format
608 : * suitable for user display in the locale specified by "displayLocale".
609 : * @param displayLocale Specifies the locale to be used to display the name.
610 : * @param dispVar Receives the variant's display name.
611 : * @return A reference to "dispVar".
612 : * @stable ICU 2.0
613 : */
614 : UnicodeString& getDisplayVariant( const Locale& displayLocale,
615 : UnicodeString& dispVar) const;
616 :
617 : /**
618 : * Fills in "name" with the name of this locale in a format suitable for user display
619 : * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(),
620 : * and getDisplayVariant() to do its work, and outputs the display name in the format
621 : * "language (country[,variant])". For example, if the default locale is en_US, then
622 : * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
623 : * would be "Spanish (Mexico,Traditional)".
624 : * @param name Receives the locale's display name.
625 : * @return A reference to "name".
626 : * @stable ICU 2.0
627 : */
628 : UnicodeString& getDisplayName( UnicodeString& name) const;
629 :
630 : /**
631 : * Fills in "name" with the name of this locale in a format suitable for user display
632 : * in the locale specfied by "displayLocale". This function uses getDisplayLanguage(),
633 : * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
634 : * name in the format "language (country[,variant])". For example, if displayLocale is
635 : * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's
636 : * display name would be "norvégien (Norvège,NY)".
637 : * @param displayLocale Specifies the locale to be used to display the name.
638 : * @param name Receives the locale's display name.
639 : * @return A reference to "name".
640 : * @stable ICU 2.0
641 : */
642 : UnicodeString& getDisplayName( const Locale& displayLocale,
643 : UnicodeString& name) const;
644 :
645 : /**
646 : * Generates a hash code for the locale.
647 : * @stable ICU 2.0
648 : */
649 : int32_t hashCode(void) const;
650 :
651 : /**
652 : * Sets the locale to bogus
653 : * A bogus locale represents a non-existing locale associated
654 : * with services that can be instantiated from non-locale data
655 : * in addition to locale (for example, collation can be
656 : * instantiated from a locale and from a rule set).
657 : * @stable ICU 2.1
658 : */
659 : void setToBogus();
660 :
661 : /**
662 : * Gets the bogus state. Locale object can be bogus if it doesn't exist
663 : * @return FALSE if it is a real locale, TRUE if it is a bogus locale
664 : * @stable ICU 2.1
665 : */
666 : UBool isBogus(void) const;
667 :
668 : /**
669 : * Returns a list of all installed locales.
670 : * @param count Receives the number of locales in the list.
671 : * @return A pointer to an array of Locale objects. This array is the list
672 : * of all locales with installed resource files. The called does NOT
673 : * get ownership of this list, and must NOT delete it.
674 : * @stable ICU 2.0
675 : */
676 : static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
677 :
678 : /**
679 : * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a
680 : * pointer to an array of pointers to arrays of char. All of these pointers are
681 : * owned by ICU-- do not delete them, and do not write through them. The array is
682 : * terminated with a null pointer.
683 : * @return a list of all available country codes
684 : * @stable ICU 2.0
685 : */
686 : static const char* const* U_EXPORT2 getISOCountries();
687 :
688 : /**
689 : * Gets a list of all available language codes defined in ISO 639. This is a pointer
690 : * to an array of pointers to arrays of char. All of these pointers are owned
691 : * by ICU-- do not delete them, and do not write through them. The array is
692 : * terminated with a null pointer.
693 : * @return a list of all available language codes
694 : * @stable ICU 2.0
695 : */
696 : static const char* const* U_EXPORT2 getISOLanguages();
697 :
698 : /**
699 : * ICU "poor man's RTTI", returns a UClassID for this class.
700 : *
701 : * @stable ICU 2.2
702 : */
703 : static UClassID U_EXPORT2 getStaticClassID();
704 :
705 : /**
706 : * ICU "poor man's RTTI", returns a UClassID for the actual class.
707 : *
708 : * @stable ICU 2.2
709 : */
710 : virtual UClassID getDynamicClassID() const;
711 :
712 : protected: /* only protected for testing purposes. DO NOT USE. */
713 : #ifndef U_HIDE_INTERNAL_API
714 : /**
715 : * Set this from a single POSIX style locale string.
716 : * @internal
717 : */
718 : void setFromPOSIXID(const char *posixID);
719 : #endif /* U_HIDE_INTERNAL_API */
720 :
721 : private:
722 : /**
723 : * Initialize the locale object with a new name.
724 : * Was deprecated - used in implementation - moved internal
725 : *
726 : * @param cLocaleID The new locale name.
727 : * @param canonicalize whether to call uloc_canonicalize on cLocaleID
728 : */
729 : Locale& init(const char* cLocaleID, UBool canonicalize);
730 :
731 : /*
732 : * Internal constructor to allow construction of a locale object with
733 : * NO side effects. (Default constructor tries to get
734 : * the default locale.)
735 : */
736 : enum ELocaleType {
737 : eBOGUS
738 : };
739 : Locale(ELocaleType);
740 :
741 : /**
742 : * Initialize the locale cache for commonly used locales
743 : */
744 : static Locale *getLocaleCache(void);
745 :
746 : char language[ULOC_LANG_CAPACITY];
747 : char script[ULOC_SCRIPT_CAPACITY];
748 : char country[ULOC_COUNTRY_CAPACITY];
749 : int32_t variantBegin;
750 : char* fullName;
751 : char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
752 : // name without keywords
753 : char* baseName;
754 : void initBaseName(UErrorCode& status);
755 :
756 : UBool fIsBogus;
757 :
758 : static const Locale &getLocale(int locid);
759 :
760 : /**
761 : * A friend to allow the default locale to be set by either the C or C++ API.
762 : * @internal
763 : */
764 : friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
765 :
766 : /**
767 : * @internal
768 : */
769 : friend void U_CALLCONV locale_available_init();
770 : };
771 :
772 : inline UBool
773 0 : Locale::operator!=(const Locale& other) const
774 : {
775 0 : return !operator==(other);
776 : }
777 :
778 : inline const char *
779 0 : Locale::getCountry() const
780 : {
781 0 : return country;
782 : }
783 :
784 : inline const char *
785 0 : Locale::getLanguage() const
786 : {
787 0 : return language;
788 : }
789 :
790 : inline const char *
791 0 : Locale::getScript() const
792 : {
793 0 : return script;
794 : }
795 :
796 : inline const char *
797 0 : Locale::getVariant() const
798 : {
799 0 : return &baseName[variantBegin];
800 : }
801 :
802 : inline const char *
803 4 : Locale::getName() const
804 : {
805 4 : return fullName;
806 : }
807 :
808 : inline UBool
809 1 : Locale::isBogus(void) const {
810 1 : return fIsBogus;
811 : }
812 :
813 : U_NAMESPACE_END
814 :
815 : #endif
|
