• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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/bytestream.h"
35 #include "unicode/localpointer.h"
36 #include "unicode/strenum.h"
37 #include "unicode/stringpiece.h"
38 #include "unicode/utypes.h"
39 #include "unicode/uobject.h"
40 #include "unicode/putil.h"
41 #include "unicode/uloc.h"
42 
43 /**
44  * \file
45  * \brief C++ API: Locale ID object.
46  */
47 
48 U_NAMESPACE_BEGIN
49 
50 // Forward Declarations
51 void U_CALLCONV locale_available_init(); /**< @internal */
52 
53 class StringEnumeration;
54 class UnicodeString;
55 
56 /**
57  * A <code>Locale</code> object represents a specific geographical, political,
58  * or cultural region. An operation that requires a <code>Locale</code> to perform
59  * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
60  * to tailor information for the user. For example, displaying a number
61  * is a locale-sensitive operation--the number should be formatted
62  * according to the customs/conventions of the user's native country,
63  * region, or culture.
64  *
65  * The Locale class is not suitable for subclassing.
66  *
67  * <P>
68  * You can create a <code>Locale</code> object using the constructor in
69  * this class:
70  * \htmlonly<blockquote>\endhtmlonly
71  * <pre>
72  *       Locale( const   char*  language,
73  *               const   char*  country,
74  *               const   char*  variant);
75  * </pre>
76  * \htmlonly</blockquote>\endhtmlonly
77  * The first argument to the constructors is a valid <STRONG>ISO
78  * Language Code.</STRONG> These codes are the lower-case two-letter
79  * codes as defined by ISO-639.
80  * You can find a full list of these codes at:
81  * <BR><a href ="http://www.loc.gov/standards/iso639-2/">
82  * http://www.loc.gov/standards/iso639-2/</a>
83  *
84  * <P>
85  * The second argument to the constructors is a valid <STRONG>ISO Country
86  * Code.</STRONG> These codes are the upper-case two-letter codes
87  * as defined by ISO-3166.
88  * You can find a full list of these codes at a number of sites, such as:
89  * <BR><a href="http://www.iso.org/iso/en/prods-services/iso3166ma/index.html">
90  * http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</a>
91  *
92  * <P>
93  * The third constructor requires a third argument--the <STRONG>Variant.</STRONG>
94  * The Variant codes are vendor and browser-specific.
95  * For example, use REVISED for a language's revised script orthography, and POSIX for POSIX.
96  * Where there are two variants, separate them with an underscore, and
97  * put the most important one first. For
98  * example, a Traditional Spanish collation might be referenced, with
99  * "ES", "ES", "Traditional_POSIX".
100  *
101  * <P>
102  * Because a <code>Locale</code> object is just an identifier for a region,
103  * no validity check is performed when you construct a <code>Locale</code>.
104  * If you want to see whether particular resources are available for the
105  * <code>Locale</code> you construct, you must query those resources. For
106  * example, ask the <code>NumberFormat</code> for the locales it supports
107  * using its <code>getAvailableLocales</code> method.
108  * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
109  * locale, you get back the best available match, not necessarily
110  * precisely what you asked for. For more information, look at
111  * <code>ResourceBundle</code>.
112  *
113  * <P>
114  * The <code>Locale</code> class provides a number of convenient constants
115  * that you can use to create <code>Locale</code> objects for commonly used
116  * locales. For example, the following refers to a <code>Locale</code> object
117  * for the United States:
118  * \htmlonly<blockquote>\endhtmlonly
119  * <pre>
120  *       Locale::getUS()
121  * </pre>
122  * \htmlonly</blockquote>\endhtmlonly
123  *
124  * <P>
125  * Once you've created a <code>Locale</code> you can query it for information about
126  * itself. Use <code>getCountry</code> to get the ISO Country Code and
127  * <code>getLanguage</code> to get the ISO Language Code. You can
128  * use <code>getDisplayCountry</code> to get the
129  * name of the country suitable for displaying to the user. Similarly,
130  * you can use <code>getDisplayLanguage</code> to get the name of
131  * the language suitable for displaying to the user. Interestingly,
132  * the <code>getDisplayXXX</code> methods are themselves locale-sensitive
133  * and have two versions: one that uses the default locale and one
134  * that takes a locale as an argument and displays the name or country in
135  * a language appropriate to that locale.
136  *
137  * <P>
138  * ICU provides a number of classes that perform locale-sensitive
139  * operations. For example, the <code>NumberFormat</code> class formats
140  * numbers, currency, or percentages in a locale-sensitive manner. Classes
141  * such as <code>NumberFormat</code> have a number of convenience methods
142  * for creating a default object of that type. For example, the
143  * <code>NumberFormat</code> class provides these three convenience methods
144  * for creating a default <code>NumberFormat</code> object:
145  * \htmlonly<blockquote>\endhtmlonly
146  * <pre>
147  *     UErrorCode success = U_ZERO_ERROR;
148  *     Locale myLocale;
149  *     NumberFormat *nf;
150  *
151  *     nf = NumberFormat::createInstance( success );          delete nf;
152  *     nf = NumberFormat::createCurrencyInstance( success );  delete nf;
153  *     nf = NumberFormat::createPercentInstance( success );   delete nf;
154  * </pre>
155  * \htmlonly</blockquote>\endhtmlonly
156  * Each of these methods has two variants; one with an explicit locale
157  * and one without; the latter using the default locale.
158  * \htmlonly<blockquote>\endhtmlonly
159  * <pre>
160  *     nf = NumberFormat::createInstance( myLocale, success );          delete nf;
161  *     nf = NumberFormat::createCurrencyInstance( myLocale, success );  delete nf;
162  *     nf = NumberFormat::createPercentInstance( myLocale, success );   delete nf;
163  * </pre>
164  * \htmlonly</blockquote>\endhtmlonly
165  * A <code>Locale</code> is the mechanism for identifying the kind of object
166  * (<code>NumberFormat</code>) that you would like to get. The locale is
167  * <STRONG>just</STRONG> a mechanism for identifying objects,
168  * <STRONG>not</STRONG> a container for the objects themselves.
169  *
170  * <P>
171  * Each class that performs locale-sensitive operations allows you
172  * to get all the available objects of that type. You can sift
173  * through these objects by language, country, or variant,
174  * and use the display names to present a menu to the user.
175  * For example, you can create a menu of all the collation objects
176  * suitable for a given language. Such classes implement these
177  * three class methods:
178  * \htmlonly<blockquote>\endhtmlonly
179  * <pre>
180  *       static Locale* getAvailableLocales(int32_t& numLocales)
181  *       static UnicodeString& getDisplayName(const Locale&  objectLocale,
182  *                                            const Locale&  displayLocale,
183  *                                            UnicodeString& displayName)
184  *       static UnicodeString& getDisplayName(const Locale&  objectLocale,
185  *                                            UnicodeString& displayName)
186  * </pre>
187  * \htmlonly</blockquote>\endhtmlonly
188  *
189  * @stable ICU 2.0
190  * @see ResourceBundle
191  */
192 class U_COMMON_API Locale : public UObject {
193 public:
194     /** Useful constant for the Root locale. @stable ICU 4.4 */
195     static const Locale &U_EXPORT2 getRoot(void);
196     /** Useful constant for this language. @stable ICU 2.0 */
197     static const Locale &U_EXPORT2 getEnglish(void);
198     /** Useful constant for this language. @stable ICU 2.0 */
199     static const Locale &U_EXPORT2 getFrench(void);
200     /** Useful constant for this language. @stable ICU 2.0 */
201     static const Locale &U_EXPORT2 getGerman(void);
202     /** Useful constant for this language. @stable ICU 2.0 */
203     static const Locale &U_EXPORT2 getItalian(void);
204     /** Useful constant for this language. @stable ICU 2.0 */
205     static const Locale &U_EXPORT2 getJapanese(void);
206     /** Useful constant for this language. @stable ICU 2.0 */
207     static const Locale &U_EXPORT2 getKorean(void);
208     /** Useful constant for this language. @stable ICU 2.0 */
209     static const Locale &U_EXPORT2 getChinese(void);
210     /** Useful constant for this language. @stable ICU 2.0 */
211     static const Locale &U_EXPORT2 getSimplifiedChinese(void);
212     /** Useful constant for this language. @stable ICU 2.0 */
213     static const Locale &U_EXPORT2 getTraditionalChinese(void);
214 
215     /** Useful constant for this country/region. @stable ICU 2.0 */
216     static const Locale &U_EXPORT2 getFrance(void);
217     /** Useful constant for this country/region. @stable ICU 2.0 */
218     static const Locale &U_EXPORT2 getGermany(void);
219     /** Useful constant for this country/region. @stable ICU 2.0 */
220     static const Locale &U_EXPORT2 getItaly(void);
221     /** Useful constant for this country/region. @stable ICU 2.0 */
222     static const Locale &U_EXPORT2 getJapan(void);
223     /** Useful constant for this country/region. @stable ICU 2.0 */
224     static const Locale &U_EXPORT2 getKorea(void);
225     /** Useful constant for this country/region. @stable ICU 2.0 */
226     static const Locale &U_EXPORT2 getChina(void);
227     /** Useful constant for this country/region. @stable ICU 2.0 */
228     static const Locale &U_EXPORT2 getPRC(void);
229     /** Useful constant for this country/region. @stable ICU 2.0 */
230     static const Locale &U_EXPORT2 getTaiwan(void);
231     /** Useful constant for this country/region. @stable ICU 2.0 */
232     static const Locale &U_EXPORT2 getUK(void);
233     /** Useful constant for this country/region. @stable ICU 2.0 */
234     static const Locale &U_EXPORT2 getUS(void);
235     /** Useful constant for this country/region. @stable ICU 2.0 */
236     static const Locale &U_EXPORT2 getCanada(void);
237     /** Useful constant for this country/region. @stable ICU 2.0 */
238     static const Locale &U_EXPORT2 getCanadaFrench(void);
239 
240 
241     /**
242      * Construct a default locale object, a Locale for the default locale ID.
243      *
244      * @see getDefault
245      * @see uloc_getDefault
246      * @stable ICU 2.0
247      */
248     Locale();
249 
250     /**
251      * Construct a locale from language, country, variant.
252      * If an error occurs, then the constructed object will be "bogus"
253      * (isBogus() will return TRUE).
254      *
255      * @param language Lowercase two-letter or three-letter ISO-639 code.
256      *  This parameter can instead be an ICU style C locale (e.g. "en_US"),
257      *  but the other parameters must not be used.
258      *  This parameter can be NULL; if so,
259      *  the locale is initialized to match the current default locale.
260      *  (This is the same as using the default constructor.)
261      *  Please note: The Java Locale class does NOT accept the form
262      *  'new Locale("en_US")' but only 'new Locale("en","US")'
263      *
264      * @param country  Uppercase two-letter ISO-3166 code. (optional)
265      * @param variant  Uppercase vendor and browser specific code. See class
266      *                 description. (optional)
267      * @param keywordsAndValues A string consisting of keyword/values pairs, such as
268      *                 "collation=phonebook;currency=euro"
269      *
270      * @see getDefault
271      * @see uloc_getDefault
272      * @stable ICU 2.0
273      */
274     Locale( const   char * language,
275             const   char * country  = 0,
276             const   char * variant  = 0,
277             const   char * keywordsAndValues = 0);
278 
279     /**
280      * Initializes a Locale object from another Locale object.
281      *
282      * @param other The Locale object being copied in.
283      * @stable ICU 2.0
284      */
285     Locale(const    Locale& other);
286 
287 #ifndef U_HIDE_DRAFT_API
288     /**
289      * Move constructor; might leave source in bogus state.
290      * This locale will have the same contents that the source locale had.
291      *
292      * @param other The Locale object being moved in.
293      * @draft ICU 63
294      */
295     Locale(Locale&& other) U_NOEXCEPT;
296 #endif  // U_HIDE_DRAFT_API
297 
298     /**
299      * Destructor
300      * @stable ICU 2.0
301      */
302     virtual ~Locale() ;
303 
304     /**
305      * Replaces the entire contents of *this with the specified value.
306      *
307      * @param other The Locale object being copied in.
308      * @return      *this
309      * @stable ICU 2.0
310      */
311     Locale& operator=(const Locale& other);
312 
313 #ifndef U_HIDE_DRAFT_API
314     /**
315      * Move assignment operator; might leave source in bogus state.
316      * This locale will have the same contents that the source locale had.
317      * The behavior is undefined if *this and the source are the same object.
318      *
319      * @param other The Locale object being moved in.
320      * @return      *this
321      * @draft ICU 63
322      */
323     Locale& operator=(Locale&& other) U_NOEXCEPT;
324 #endif  // U_HIDE_DRAFT_API
325 
326     /**
327      * Checks if two locale keys are the same.
328      *
329      * @param other The locale key object to be compared with this.
330      * @return      True if the two locale keys are the same, false otherwise.
331      * @stable ICU 2.0
332      */
333     UBool   operator==(const    Locale&     other) const;
334 
335     /**
336      * Checks if two locale keys are not the same.
337      *
338      * @param other The locale key object to be compared with this.
339      * @return      True if the two locale keys are not the same, false
340      *              otherwise.
341      * @stable ICU 2.0
342      */
343     UBool   operator!=(const    Locale&     other) const;
344 
345     /**
346      * Clone this object.
347      * Clones can be used concurrently in multiple threads.
348      * If an error occurs, then NULL is returned.
349      * The caller must delete the clone.
350      *
351      * @return a clone of this object
352      *
353      * @see getDynamicClassID
354      * @stable ICU 2.8
355      */
356     Locale *clone() const;
357 
358 #ifndef U_HIDE_SYSTEM_API
359     /**
360      * Common methods of getting the current default Locale. Used for the
361      * presentation: menus, dialogs, etc. Generally set once when your applet or
362      * application is initialized, then never reset. (If you do reset the
363      * default locale, you probably want to reload your GUI, so that the change
364      * is reflected in your interface.)
365      *
366      * More advanced programs will allow users to use different locales for
367      * different fields, e.g. in a spreadsheet.
368      *
369      * Note that the initial setting will match the host system.
370      * @return a reference to the Locale object for the default locale ID
371      * @system
372      * @stable ICU 2.0
373      */
374     static const Locale& U_EXPORT2 getDefault(void);
375 
376     /**
377      * Sets the default. Normally set once at the beginning of a process,
378      * then never reset.
379      * setDefault() only changes ICU's default locale ID, <strong>not</strong>
380      * the default locale ID of the runtime environment.
381      *
382      * @param newLocale Locale to set to.  If NULL, set to the value obtained
383      *                  from the runtime environment.
384      * @param success The error code.
385      * @system
386      * @stable ICU 2.0
387      */
388     static void U_EXPORT2 setDefault(const Locale& newLocale,
389                                      UErrorCode&   success);
390 #endif  /* U_HIDE_SYSTEM_API */
391 
392 #ifndef U_HIDE_DRAFT_API
393     /**
394      * Returns a Locale for the specified BCP47 language tag string.
395      * If the specified language tag contains any ill-formed subtags,
396      * the first such subtag and all following subtags are ignored.
397      * <p>
398      * This implements the 'Language-Tag' production of BCP47, and so
399      * supports grandfathered (regular and irregular) as well as private
400      * use language tags.  Private use tags are represented as 'x-whatever',
401      * and grandfathered tags are converted to their canonical replacements
402      * where they exist.  Note that a few grandfathered tags have no modern
403      * replacement, these will be converted using the fallback described in
404      * the first paragraph, so some information might be lost.
405      * @param tag     the input BCP47 language tag.
406      * @param status  error information if creating the Locale failed.
407      * @return        the Locale for the specified BCP47 language tag.
408      * @draft ICU 63
409      */
410     static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status);
411 
412     /**
413      * Returns a well-formed language tag for this Locale.
414      * <p>
415      * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
416      * requirement will be silently omitted from the result.
417      *
418      * If this function fails, partial output may have been written to the sink.
419      *
420      * @param sink    the output sink receiving the BCP47 language
421      *                tag for this Locale.
422      * @param status  error information if creating the language tag failed.
423      * @draft ICU 63
424      */
425     void toLanguageTag(ByteSink& sink, UErrorCode& status) const;
426 
427     /**
428      * Returns a well-formed language tag for this Locale.
429      * <p>
430      * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
431      * requirement will be silently omitted from the result.
432      *
433      * @param status  error information if creating the language tag failed.
434      * @return        the BCP47 language tag for this Locale.
435      * @draft ICU 63
436      */
437     template<typename StringClass>
438     inline StringClass toLanguageTag(UErrorCode& status) const;
439 #endif  // U_HIDE_DRAFT_API
440 
441     /**
442      * Creates a locale which has had minimal canonicalization
443      * as per uloc_getName().
444      * @param name The name to create from.  If name is null,
445      *  the default Locale is used.
446      * @return new locale object
447      * @stable ICU 2.0
448      * @see uloc_getName
449      */
450     static Locale U_EXPORT2 createFromName(const char *name);
451 
452     /**
453      * Creates a locale from the given string after canonicalizing
454      * the string by calling uloc_canonicalize().
455      * @param name the locale ID to create from.  Must not be NULL.
456      * @return a new locale object corresponding to the given name
457      * @stable ICU 3.0
458      * @see uloc_canonicalize
459      */
460     static Locale U_EXPORT2 createCanonical(const char* name);
461 
462     /**
463      * Returns the locale's ISO-639 language code.
464      * @return      An alias to the code
465      * @stable ICU 2.0
466      */
467     inline const char *  getLanguage( ) const;
468 
469     /**
470      * Returns the locale's ISO-15924 abbreviation script code.
471      * @return      An alias to the code
472      * @see uscript_getShortName
473      * @see uscript_getCode
474      * @stable ICU 2.8
475      */
476     inline const char *  getScript( ) const;
477 
478     /**
479      * Returns the locale's ISO-3166 country code.
480      * @return      An alias to the code
481      * @stable ICU 2.0
482      */
483     inline const char *  getCountry( ) const;
484 
485     /**
486      * Returns the locale's variant code.
487      * @return      An alias to the code
488      * @stable ICU 2.0
489      */
490     inline const char *  getVariant( ) const;
491 
492     /**
493      * Returns the programmatic name of the entire locale, with the language,
494      * country and variant separated by underbars. If a field is missing, up
495      * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
496      * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
497      * @return      A pointer to "name".
498      * @stable ICU 2.0
499      */
500     inline const char * getName() const;
501 
502     /**
503      * Returns the programmatic name of the entire locale as getName() would return,
504      * but without keywords.
505      * @return      A pointer to "name".
506      * @see getName
507      * @stable ICU 2.8
508      */
509     const char * getBaseName() const;
510 
511 #ifndef U_HIDE_DRAFT_API
512     /**
513      * Add the likely subtags for this Locale, per the algorithm described
514      * in the following CLDR technical report:
515      *
516      *   http://www.unicode.org/reports/tr35/#Likely_Subtags
517      *
518      * If this Locale is already in the maximal form, or not valid, or there is
519      * no data available for maximization, the Locale will be unchanged.
520      *
521      * For example, "und-Zzzz" cannot be maximized, since there is no
522      * reasonable maximization.
523      *
524      * Examples:
525      *
526      * "en" maximizes to "en_Latn_US"
527      *
528      * "de" maximizes to "de_Latn_US"
529      *
530      * "sr" maximizes to "sr_Cyrl_RS"
531      *
532      * "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.)
533      *
534      * "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)
535      *
536      * @param status  error information if maximizing this Locale failed.
537      *                If this Locale is not well-formed, the error code is
538      *                U_ILLEGAL_ARGUMENT_ERROR.
539      * @draft ICU 63
540      */
541     void addLikelySubtags(UErrorCode& status);
542 
543     /**
544      * Minimize the subtags for this Locale, per the algorithm described
545      * in the following CLDR technical report:
546      *
547      *   http://www.unicode.org/reports/tr35/#Likely_Subtags
548      *
549      * If this Locale is already in the minimal form, or not valid, or there is
550      * no data available for minimization, the Locale will be unchanged.
551      *
552      * Since the minimization algorithm relies on proper maximization, see the
553      * comments for addLikelySubtags for reasons why there might not be any
554      * data.
555      *
556      * Examples:
557      *
558      * "en_Latn_US" minimizes to "en"
559      *
560      * "de_Latn_US" minimizes to "de"
561      *
562      * "sr_Cyrl_RS" minimizes to "sr"
563      *
564      * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the
565      * script, and minimizing to "zh" would imply "zh_Hans_CN".)
566      *
567      * @param status  error information if maximizing this Locale failed.
568      *                If this Locale is not well-formed, the error code is
569      *                U_ILLEGAL_ARGUMENT_ERROR.
570      * @draft ICU 63
571      */
572     void minimizeSubtags(UErrorCode& status);
573 #endif  // U_HIDE_DRAFT_API
574 
575     /**
576      * Gets the list of keywords for the specified locale.
577      *
578      * @param status the status code
579      * @return pointer to StringEnumeration class, or NULL if there are no keywords.
580      * Client must dispose of it by calling delete.
581      * @see getKeywords
582      * @stable ICU 2.8
583      */
584     StringEnumeration * createKeywords(UErrorCode &status) const;
585 
586 #ifndef U_HIDE_DRAFT_API
587 
588     /**
589      * Gets the list of Unicode keywords for the specified locale.
590      *
591      * @param status the status code
592      * @return pointer to StringEnumeration class, or NULL if there are no keywords.
593      * Client must dispose of it by calling delete.
594      * @see getUnicodeKeywords
595      * @draft ICU 63
596      */
597     StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
598 
599     /**
600      * Gets the set of keywords for this Locale.
601      *
602      * A wrapper to call createKeywords() and write the resulting
603      * keywords as standard strings (or compatible objects) into any kind of
604      * container that can be written to by an STL style output iterator.
605      *
606      * @param iterator  an STL style output iterator to write the keywords to.
607      * @param status    error information if creating set of keywords failed.
608      * @draft ICU 63
609      */
610     template<typename StringClass, typename OutputIterator>
611     inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
612 
613     /**
614      * Gets the set of Unicode keywords for this Locale.
615      *
616      * A wrapper to call createUnicodeKeywords() and write the resulting
617      * keywords as standard strings (or compatible objects) into any kind of
618      * container that can be written to by an STL style output iterator.
619      *
620      * @param iterator  an STL style output iterator to write the keywords to.
621      * @param status    error information if creating set of keywords failed.
622      * @draft ICU 63
623      */
624     template<typename StringClass, typename OutputIterator>
625     inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
626 
627 #endif  // U_HIDE_DRAFT_API
628 
629     /**
630      * Gets the value for a keyword.
631      *
632      * This uses legacy keyword=value pairs, like "collation=phonebook".
633      *
634      * ICU4C doesn't do automatic conversion between legacy and Unicode
635      * keywords and values in getters and setters (as opposed to ICU4J).
636      *
637      * @param keywordName name of the keyword for which we want the value. Case insensitive.
638      * @param buffer The buffer to receive the keyword value.
639      * @param bufferCapacity The capacity of receiving buffer
640      * @param status Returns any error information while performing this operation.
641      * @return the length of the keyword value
642      *
643      * @stable ICU 2.8
644      */
645     int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
646 
647 #ifndef U_HIDE_DRAFT_API
648     /**
649      * Gets the value for a keyword.
650      *
651      * This uses legacy keyword=value pairs, like "collation=phonebook".
652      *
653      * ICU4C doesn't do automatic conversion between legacy and Unicode
654      * keywords and values in getters and setters (as opposed to ICU4J).
655      *
656      * @param keywordName  name of the keyword for which we want the value.
657      * @param sink         the sink to receive the keyword value.
658      * @param status       error information if getting the value failed.
659      * @draft ICU 63
660      */
661     void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
662 
663     /**
664      * Gets the value for a keyword.
665      *
666      * This uses legacy keyword=value pairs, like "collation=phonebook".
667      *
668      * ICU4C doesn't do automatic conversion between legacy and Unicode
669      * keywords and values in getters and setters (as opposed to ICU4J).
670      *
671      * @param keywordName  name of the keyword for which we want the value.
672      * @param status       error information if getting the value failed.
673      * @return             the keyword value.
674      * @draft ICU 63
675      */
676     template<typename StringClass>
677     inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
678 
679     /**
680      * Gets the Unicode value for a Unicode keyword.
681      *
682      * This uses Unicode key-value pairs, like "co-phonebk".
683      *
684      * ICU4C doesn't do automatic conversion between legacy and Unicode
685      * keywords and values in getters and setters (as opposed to ICU4J).
686      *
687      * @param keywordName  name of the keyword for which we want the value.
688      * @param sink         the sink to receive the keyword value.
689      * @param status       error information if getting the value failed.
690      * @draft ICU 63
691      */
692     void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
693 
694     /**
695      * Gets the Unicode value for a Unicode keyword.
696      *
697      * This uses Unicode key-value pairs, like "co-phonebk".
698      *
699      * ICU4C doesn't do automatic conversion between legacy and Unicode
700      * keywords and values in getters and setters (as opposed to ICU4J).
701      *
702      * @param keywordName  name of the keyword for which we want the value.
703      * @param status       error information if getting the value failed.
704      * @return             the keyword value.
705      * @draft ICU 63
706      */
707     template<typename StringClass>
708     inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
709 #endif  // U_HIDE_DRAFT_API
710 
711     /**
712      * Sets or removes the value for a keyword.
713      *
714      * For removing all keywords, use getBaseName(),
715      * and construct a new Locale if it differs from getName().
716      *
717      * This uses legacy keyword=value pairs, like "collation=phonebook".
718      *
719      * ICU4C doesn't do automatic conversion between legacy and Unicode
720      * keywords and values in getters and setters (as opposed to ICU4J).
721      *
722      * @param keywordName name of the keyword to be set. Case insensitive.
723      * @param keywordValue value of the keyword to be set. If 0-length or
724      *  NULL, will result in the keyword being removed. No error is given if
725      *  that keyword does not exist.
726      * @param status Returns any error information while performing this operation.
727      *
728      * @stable ICU 49
729      */
730     void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
731 
732 #ifndef U_HIDE_DRAFT_API
733     /**
734      * Sets or removes the value for a keyword.
735      *
736      * For removing all keywords, use getBaseName(),
737      * and construct a new Locale if it differs from getName().
738      *
739      * This uses legacy keyword=value pairs, like "collation=phonebook".
740      *
741      * ICU4C doesn't do automatic conversion between legacy and Unicode
742      * keywords and values in getters and setters (as opposed to ICU4J).
743      *
744      * @param keywordName name of the keyword to be set.
745      * @param keywordValue value of the keyword to be set. If 0-length or
746      *  NULL, will result in the keyword being removed. No error is given if
747      *  that keyword does not exist.
748      * @param status Returns any error information while performing this operation.
749      * @draft ICU 63
750      */
751     void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
752 
753     /**
754      * Sets or removes the Unicode value for a Unicode keyword.
755      *
756      * For removing all keywords, use getBaseName(),
757      * and construct a new Locale if it differs from getName().
758      *
759      * This uses Unicode key-value pairs, like "co-phonebk".
760      *
761      * ICU4C doesn't do automatic conversion between legacy and Unicode
762      * keywords and values in getters and setters (as opposed to ICU4J).
763      *
764      * @param keywordName name of the keyword to be set.
765      * @param keywordValue value of the keyword to be set. If 0-length or
766      *  NULL, will result in the keyword being removed. No error is given if
767      *  that keyword does not exist.
768      * @param status Returns any error information while performing this operation.
769      * @draft ICU 63
770      */
771     void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
772 #endif  // U_HIDE_DRAFT_API
773 
774     /**
775      * returns the locale's three-letter language code, as specified
776      * in ISO draft standard ISO-639-2.
777      * @return      An alias to the code, or an empty string
778      * @stable ICU 2.0
779      */
780     const char * getISO3Language() const;
781 
782     /**
783      * Fills in "name" with the locale's three-letter ISO-3166 country code.
784      * @return      An alias to the code, or an empty string
785      * @stable ICU 2.0
786      */
787     const char * getISO3Country() const;
788 
789     /**
790      * Returns the Windows LCID value corresponding to this locale.
791      * This value is stored in the resource data for the locale as a one-to-four-digit
792      * hexadecimal number.  If the resource is missing, in the wrong format, or
793      * there is no Windows LCID value that corresponds to this locale, returns 0.
794      * @stable ICU 2.0
795      */
796     uint32_t        getLCID(void) const;
797 
798     /**
799      * Returns whether this locale's script is written right-to-left.
800      * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
801      * If no likely script is known, then FALSE is returned.
802      *
803      * A script is right-to-left according to the CLDR script metadata
804      * which corresponds to whether the script's letters have Bidi_Class=R or AL.
805      *
806      * Returns TRUE for "ar" and "en-Hebr", FALSE for "zh" and "fa-Cyrl".
807      *
808      * @return TRUE if the locale's script is written right-to-left
809      * @stable ICU 54
810      */
811     UBool isRightToLeft() const;
812 
813     /**
814      * Fills in "dispLang" with the name of this locale's language in a format suitable for
815      * user display in the default locale.  For example, if the locale's language code is
816      * "fr" and the default locale's language code is "en", this function would set
817      * dispLang to "French".
818      * @param dispLang  Receives the language's display name.
819      * @return          A reference to "dispLang".
820      * @stable ICU 2.0
821      */
822     UnicodeString&  getDisplayLanguage(UnicodeString&   dispLang) const;
823 
824     /**
825      * Fills in "dispLang" with the name of this locale's language in a format suitable for
826      * user display in the locale specified by "displayLocale".  For example, if the locale's
827      * language code is "en" and displayLocale's language code is "fr", this function would set
828      * dispLang to "Anglais".
829      * @param displayLocale  Specifies the locale to be used to display the name.  In other words,
830      *                  if the locale's language code is "en", passing Locale::getFrench() for
831      *                  displayLocale would result in "Anglais", while passing Locale::getGerman()
832      *                  for displayLocale would result in "Englisch".
833      * @param dispLang  Receives the language's display name.
834      * @return          A reference to "dispLang".
835      * @stable ICU 2.0
836      */
837     UnicodeString&  getDisplayLanguage( const   Locale&         displayLocale,
838                                                 UnicodeString&  dispLang) const;
839 
840     /**
841      * Fills in "dispScript" with the name of this locale's script in a format suitable
842      * for user display in the default locale.  For example, if the locale's script code
843      * is "LATN" and the default locale's language code is "en", this function would set
844      * dispScript to "Latin".
845      * @param dispScript    Receives the scripts's display name.
846      * @return              A reference to "dispScript".
847      * @stable ICU 2.8
848      */
849     UnicodeString&  getDisplayScript(          UnicodeString& dispScript) const;
850 
851     /**
852      * Fills in "dispScript" with the name of this locale's country in a format suitable
853      * for user display in the locale specified by "displayLocale".  For example, if the locale's
854      * script code is "LATN" and displayLocale's language code is "en", this function would set
855      * dispScript to "Latin".
856      * @param displayLocale      Specifies the locale to be used to display the name.  In other
857      *                      words, if the locale's script code is "LATN", passing
858      *                      Locale::getFrench() for displayLocale would result in "", while
859      *                      passing Locale::getGerman() for displayLocale would result in
860      *                      "".
861      * @param dispScript    Receives the scripts's display name.
862      * @return              A reference to "dispScript".
863      * @stable ICU 2.8
864      */
865     UnicodeString&  getDisplayScript(  const   Locale&         displayLocale,
866                                                UnicodeString&  dispScript) const;
867 
868     /**
869      * Fills in "dispCountry" with the name of this locale's country in a format suitable
870      * for user display in the default locale.  For example, if the locale's country code
871      * is "FR" and the default locale's language code is "en", this function would set
872      * dispCountry to "France".
873      * @param dispCountry   Receives the country's display name.
874      * @return              A reference to "dispCountry".
875      * @stable ICU 2.0
876      */
877     UnicodeString&  getDisplayCountry(          UnicodeString& dispCountry) const;
878 
879     /**
880      * Fills in "dispCountry" with the name of this locale's country in a format suitable
881      * for user display in the locale specified by "displayLocale".  For example, if the locale's
882      * country code is "US" and displayLocale's language code is "fr", this function would set
883      * dispCountry to "&Eacute;tats-Unis".
884      * @param displayLocale      Specifies the locale to be used to display the name.  In other
885      *                      words, if the locale's country code is "US", passing
886      *                      Locale::getFrench() for displayLocale would result in "&Eacute;tats-Unis", while
887      *                      passing Locale::getGerman() for displayLocale would result in
888      *                      "Vereinigte Staaten".
889      * @param dispCountry   Receives the country's display name.
890      * @return              A reference to "dispCountry".
891      * @stable ICU 2.0
892      */
893     UnicodeString&  getDisplayCountry(  const   Locale&         displayLocale,
894                                                 UnicodeString&  dispCountry) const;
895 
896     /**
897      * Fills in "dispVar" with the name of this locale's variant code in a format suitable
898      * for user display in the default locale.
899      * @param dispVar   Receives the variant's name.
900      * @return          A reference to "dispVar".
901      * @stable ICU 2.0
902      */
903     UnicodeString&  getDisplayVariant(      UnicodeString& dispVar) const;
904 
905     /**
906      * Fills in "dispVar" with the name of this locale's variant code in a format
907      * suitable for user display in the locale specified by "displayLocale".
908      * @param displayLocale  Specifies the locale to be used to display the name.
909      * @param dispVar   Receives the variant's display name.
910      * @return          A reference to "dispVar".
911      * @stable ICU 2.0
912      */
913     UnicodeString&  getDisplayVariant(  const   Locale&         displayLocale,
914                                                 UnicodeString&  dispVar) const;
915 
916     /**
917      * Fills in "name" with the name of this locale in a format suitable for user display
918      * in the default locale.  This function uses getDisplayLanguage(), getDisplayCountry(),
919      * and getDisplayVariant() to do its work, and outputs the display name in the format
920      * "language (country[,variant])".  For example, if the default locale is en_US, then
921      * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
922      * would be "Spanish (Mexico,Traditional)".
923      * @param name  Receives the locale's display name.
924      * @return      A reference to "name".
925      * @stable ICU 2.0
926      */
927     UnicodeString&  getDisplayName(         UnicodeString&  name) const;
928 
929     /**
930      * Fills in "name" with the name of this locale in a format suitable for user display
931      * in the locale specified by "displayLocale".  This function uses getDisplayLanguage(),
932      * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
933      * name in the format "language (country[,variant])".  For example, if displayLocale is
934      * fr_FR, then en_US's display name would be "Anglais (&Eacute;tats-Unis)", and no_NO_NY's
935      * display name would be "norv&eacute;gien (Norv&egrave;ge,NY)".
936      * @param displayLocale  Specifies the locale to be used to display the name.
937      * @param name      Receives the locale's display name.
938      * @return          A reference to "name".
939      * @stable ICU 2.0
940      */
941     UnicodeString&  getDisplayName( const   Locale&         displayLocale,
942                                             UnicodeString&  name) const;
943 
944     /**
945      * Generates a hash code for the locale.
946      * @stable ICU 2.0
947      */
948     int32_t         hashCode(void) const;
949 
950     /**
951      * Sets the locale to bogus
952      * A bogus locale represents a non-existing locale associated
953      * with services that can be instantiated from non-locale data
954      * in addition to locale (for example, collation can be
955      * instantiated from a locale and from a rule set).
956      * @stable ICU 2.1
957      */
958     void setToBogus();
959 
960     /**
961      * Gets the bogus state. Locale object can be bogus if it doesn't exist
962      * @return FALSE if it is a real locale, TRUE if it is a bogus locale
963      * @stable ICU 2.1
964      */
965     UBool isBogus(void) const;
966 
967     /**
968      * Returns a list of all installed locales.
969      * @param count Receives the number of locales in the list.
970      * @return      A pointer to an array of Locale objects.  This array is the list
971      *              of all locales with installed resource files.  The called does NOT
972      *              get ownership of this list, and must NOT delete it.
973      * @stable ICU 2.0
974      */
975     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
976 
977     /**
978      * Gets a list of all available 2-letter country codes defined in ISO 3166.  This is a
979      * pointer to an array of pointers to arrays of char.  All of these pointers are
980      * owned by ICU-- do not delete them, and do not write through them.  The array is
981      * terminated with a null pointer.
982      * @return a list of all available country codes
983      * @stable ICU 2.0
984      */
985     static const char* const* U_EXPORT2 getISOCountries();
986 
987     /**
988      * Gets a list of all available language codes defined in ISO 639.  This is a pointer
989      * to an array of pointers to arrays of char.  All of these pointers are owned
990      * by ICU-- do not delete them, and do not write through them.  The array is
991      * terminated with a null pointer.
992      * @return a list of all available language codes
993      * @stable ICU 2.0
994      */
995     static const char* const* U_EXPORT2 getISOLanguages();
996 
997     /**
998      * ICU "poor man's RTTI", returns a UClassID for this class.
999      *
1000      * @stable ICU 2.2
1001      */
1002     static UClassID U_EXPORT2 getStaticClassID();
1003 
1004     /**
1005      * ICU "poor man's RTTI", returns a UClassID for the actual class.
1006      *
1007      * @stable ICU 2.2
1008      */
1009     virtual UClassID getDynamicClassID() const;
1010 
1011 protected: /* only protected for testing purposes. DO NOT USE. */
1012 #ifndef U_HIDE_INTERNAL_API
1013     /**
1014      * Set this from a single POSIX style locale string.
1015      * @internal
1016      */
1017     void setFromPOSIXID(const char *posixID);
1018 #endif  /* U_HIDE_INTERNAL_API */
1019 
1020 private:
1021     /**
1022      * Initialize the locale object with a new name.
1023      * Was deprecated - used in implementation - moved internal
1024      *
1025      * @param cLocaleID The new locale name.
1026      * @param canonicalize whether to call uloc_canonicalize on cLocaleID
1027      */
1028     Locale& init(const char* cLocaleID, UBool canonicalize);
1029 
1030     /*
1031      * Internal constructor to allow construction of a locale object with
1032      *   NO side effects.   (Default constructor tries to get
1033      *   the default locale.)
1034      */
1035     enum ELocaleType {
1036         eBOGUS
1037     };
1038     Locale(ELocaleType);
1039 
1040     /**
1041      * Initialize the locale cache for commonly used locales
1042      */
1043     static Locale *getLocaleCache(void);
1044 
1045     char language[ULOC_LANG_CAPACITY];
1046     char script[ULOC_SCRIPT_CAPACITY];
1047     char country[ULOC_COUNTRY_CAPACITY];
1048     int32_t variantBegin;
1049     char* fullName;
1050     char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1051     // name without keywords
1052     char* baseName;
1053     void initBaseName(UErrorCode& status);
1054 
1055     UBool fIsBogus;
1056 
1057     static const Locale &getLocale(int locid);
1058 
1059     /**
1060      * A friend to allow the default locale to be set by either the C or C++ API.
1061      * @internal (private)
1062      */
1063     friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1064 
1065     /**
1066      * @internal (private)
1067      */
1068     friend void U_CALLCONV locale_available_init();
1069 };
1070 
1071 inline UBool
1072 Locale::operator!=(const    Locale&     other) const
1073 {
1074     return !operator==(other);
1075 }
1076 
1077 #ifndef U_HIDE_DRAFT_API
1078 template<typename StringClass> inline StringClass
toLanguageTag(UErrorCode & status)1079 Locale::toLanguageTag(UErrorCode& status) const
1080 {
1081     StringClass result;
1082     StringByteSink<StringClass> sink(&result);
1083     toLanguageTag(sink, status);
1084     return result;
1085 }
1086 #endif  // U_HIDE_DRAFT_API
1087 
1088 inline const char *
getCountry()1089 Locale::getCountry() const
1090 {
1091     return country;
1092 }
1093 
1094 inline const char *
getLanguage()1095 Locale::getLanguage() const
1096 {
1097     return language;
1098 }
1099 
1100 inline const char *
getScript()1101 Locale::getScript() const
1102 {
1103     return script;
1104 }
1105 
1106 inline const char *
getVariant()1107 Locale::getVariant() const
1108 {
1109     return &baseName[variantBegin];
1110 }
1111 
1112 inline const char *
getName()1113 Locale::getName() const
1114 {
1115     return fullName;
1116 }
1117 
1118 #ifndef U_HIDE_DRAFT_API
1119 
1120 template<typename StringClass, typename OutputIterator> inline void
getKeywords(OutputIterator iterator,UErrorCode & status)1121 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1122 {
1123     LocalPointer<StringEnumeration> keys(createKeywords(status));
1124     if (U_FAILURE(status)) {
1125         return;
1126     }
1127     for (;;) {
1128         int32_t resultLength;
1129         const char* buffer = keys->next(&resultLength, status);
1130         if (U_FAILURE(status) || buffer == nullptr) {
1131             return;
1132         }
1133         *iterator++ = StringClass(buffer, resultLength);
1134     }
1135 }
1136 
1137 template<typename StringClass, typename OutputIterator> inline void
getUnicodeKeywords(OutputIterator iterator,UErrorCode & status)1138 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1139 {
1140     LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1141     if (U_FAILURE(status)) {
1142         return;
1143     }
1144     for (;;) {
1145         int32_t resultLength;
1146         const char* buffer = keys->next(&resultLength, status);
1147         if (U_FAILURE(status) || buffer == nullptr) {
1148             return;
1149         }
1150         *iterator++ = StringClass(buffer, resultLength);
1151     }
1152 }
1153 
1154 template<typename StringClass> inline StringClass
getKeywordValue(StringPiece keywordName,UErrorCode & status)1155 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1156 {
1157     StringClass result;
1158     StringByteSink<StringClass> sink(&result);
1159     getKeywordValue(keywordName, sink, status);
1160     return result;
1161 }
1162 
1163 template<typename StringClass> inline StringClass
getUnicodeKeywordValue(StringPiece keywordName,UErrorCode & status)1164 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1165 {
1166     StringClass result;
1167     StringByteSink<StringClass> sink(&result);
1168     getUnicodeKeywordValue(keywordName, sink, status);
1169     return result;
1170 }
1171 
1172 #endif  // U_HIDE_DRAFT_API
1173 
1174 inline UBool
isBogus(void)1175 Locale::isBogus(void) const {
1176     return fIsBogus;
1177 }
1178 
1179 U_NAMESPACE_END
1180 
1181 #endif
1182