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