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