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();
199 /** Useful constant for this language. @stable ICU 2.0 */
200 static const Locale& U_EXPORT2 getEnglish();
201 /** Useful constant for this language. @stable ICU 2.0 */
202 static const Locale& U_EXPORT2 getFrench();
203 /** Useful constant for this language. @stable ICU 2.0 */
204 static const Locale& U_EXPORT2 getGerman();
205 /** Useful constant for this language. @stable ICU 2.0 */
206 static const Locale& U_EXPORT2 getItalian();
207 /** Useful constant for this language. @stable ICU 2.0 */
208 static const Locale& U_EXPORT2 getJapanese();
209 /** Useful constant for this language. @stable ICU 2.0 */
210 static const Locale& U_EXPORT2 getKorean();
211 /** Useful constant for this language. @stable ICU 2.0 */
212 static const Locale& U_EXPORT2 getChinese();
213 /** Useful constant for this language. @stable ICU 2.0 */
214 static const Locale& U_EXPORT2 getSimplifiedChinese();
215 /** Useful constant for this language. @stable ICU 2.0 */
216 static const Locale& U_EXPORT2 getTraditionalChinese();
217
218 /** Useful constant for this country/region. @stable ICU 2.0 */
219 static const Locale& U_EXPORT2 getFrance();
220 /** Useful constant for this country/region. @stable ICU 2.0 */
221 static const Locale& U_EXPORT2 getGermany();
222 /** Useful constant for this country/region. @stable ICU 2.0 */
223 static const Locale& U_EXPORT2 getItaly();
224 /** Useful constant for this country/region. @stable ICU 2.0 */
225 static const Locale& U_EXPORT2 getJapan();
226 /** Useful constant for this country/region. @stable ICU 2.0 */
227 static const Locale& U_EXPORT2 getKorea();
228 /** Useful constant for this country/region. @stable ICU 2.0 */
229 static const Locale& U_EXPORT2 getChina();
230 /** Useful constant for this country/region. @stable ICU 2.0 */
231 static const Locale& U_EXPORT2 getPRC();
232 /** Useful constant for this country/region. @stable ICU 2.0 */
233 static const Locale& U_EXPORT2 getTaiwan();
234 /** Useful constant for this country/region. @stable ICU 2.0 */
235 static const Locale& U_EXPORT2 getUK();
236 /** Useful constant for this country/region. @stable ICU 2.0 */
237 static const Locale& U_EXPORT2 getUS();
238 /** Useful constant for this country/region. @stable ICU 2.0 */
239 static const Locale& U_EXPORT2 getCanada();
240 /** Useful constant for this country/region. @stable ICU 2.0 */
241 static const Locale& U_EXPORT2 getCanadaFrench();
242
243 /**
244 * Construct a default locale object, a Locale for the default locale ID.
245 *
246 * @see getDefault
247 * @see uloc_getDefault
248 * @stable ICU 2.0
249 */
250 Locale();
251
252 /**
253 * Construct a locale from language, country, variant.
254 * If an error occurs, then the constructed object will be "bogus"
255 * (isBogus() will return true).
256 *
257 * @param language Lowercase two-letter or three-letter ISO-639 code.
258 * This parameter can instead be an ICU style C locale (e.g. "en_US"),
259 * but the other parameters must not be used.
260 * This parameter can be nullptr; if so,
261 * the locale is initialized to match the current default locale.
262 * (This is the same as using the default constructor.)
263 * Please note: The Java Locale class does NOT accept the form
264 * 'new Locale("en_US")' but only 'new Locale("en","US")'
265 *
266 * @param country Uppercase two-letter ISO-3166 code. (optional)
267 * @param variant Uppercase vendor and browser specific code. See class
268 * description. (optional)
269 * @param keywordsAndValues A string consisting of keyword/values pairs, such as
270 * "collation=phonebook;currency=euro"
271 *
272 * @see getDefault
273 * @see uloc_getDefault
274 * @stable ICU 2.0
275 */
276 Locale(const char* language,
277 const char* country = nullptr,
278 const char* variant = nullptr,
279 const char* keywordsAndValues = nullptr);
280
281 /**
282 * Initializes a Locale object from another Locale object.
283 *
284 * @param other The Locale object being copied in.
285 * @stable ICU 2.0
286 */
287 Locale(const Locale& other);
288
289 /**
290 * Move constructor; might leave source in bogus state.
291 * This locale will have the same contents that the source locale had.
292 *
293 * @param other The Locale object being moved in.
294 * @stable ICU 63
295 */
296 Locale(Locale&& other) noexcept;
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 /**
314 * Move assignment operator; might leave source in bogus state.
315 * This locale will have the same contents that the source locale had.
316 * The behavior is undefined if *this and the source are the same object.
317 *
318 * @param other The Locale object being moved in.
319 * @return *this
320 * @stable ICU 63
321 */
322 Locale& operator=(Locale&& other) noexcept;
323
324 /**
325 * Checks if two locale keys are the same.
326 *
327 * @param other The locale key object to be compared with this.
328 * @return true if the two locale keys are the same, false otherwise.
329 * @stable ICU 2.0
330 */
331 bool operator==(const Locale& other) const;
332
333 /**
334 * Checks if two locale keys are not the same.
335 *
336 * @param other The locale key object to be compared with this.
337 * @return true if the two locale keys are not the same, false
338 * otherwise.
339 * @stable ICU 2.0
340 */
341 inline bool operator!=(const Locale& other) const;
342
343 /**
344 * Clone this object.
345 * Clones can be used concurrently in multiple threads.
346 * If an error occurs, then nullptr is returned.
347 * The caller must delete the clone.
348 *
349 * @return a clone of this object
350 *
351 * @see getDynamicClassID
352 * @stable ICU 2.8
353 */
354 Locale *clone() const;
355
356 #ifndef U_HIDE_SYSTEM_API
357 /**
358 * Common methods of getting the current default Locale. Used for the
359 * presentation: menus, dialogs, etc. Generally set once when your applet or
360 * application is initialized, then never reset. (If you do reset the
361 * default locale, you probably want to reload your GUI, so that the change
362 * is reflected in your interface.)
363 *
364 * More advanced programs will allow users to use different locales for
365 * different fields, e.g. in a spreadsheet.
366 *
367 * Note that the initial setting will match the host system.
368 * @return a reference to the Locale object for the default locale ID
369 * @system
370 * @stable ICU 2.0
371 */
372 static const Locale& U_EXPORT2 getDefault();
373
374 /**
375 * Sets the default. Normally set once at the beginning of a process,
376 * then never reset.
377 * setDefault() only changes ICU's default locale ID, <strong>not</strong>
378 * the default locale ID of the runtime environment.
379 *
380 * @param newLocale Locale to set to. If nullptr, set to the value obtained
381 * from the runtime environment.
382 * @param success The error code.
383 * @system
384 * @stable ICU 2.0
385 */
386 static void U_EXPORT2 setDefault(const Locale& newLocale,
387 UErrorCode& success);
388 #endif /* U_HIDE_SYSTEM_API */
389
390 /**
391 * Returns a Locale for the specified BCP47 language tag string.
392 * If the specified language tag contains any ill-formed subtags,
393 * the first such subtag and all following subtags are ignored.
394 * <p>
395 * This implements the 'Language-Tag' production of BCP 47, and so
396 * supports legacy language tags (marked as “Type: grandfathered” in BCP 47)
397 * (regular and irregular) as well as private use language tags.
398 *
399 * Private use tags are represented as 'x-whatever',
400 * and legacy tags are converted to their canonical replacements where they exist.
401 *
402 * Note that a few legacy tags have no modern replacement;
403 * these will be converted using the fallback described in
404 * the first paragraph, so some information might be lost.
405 *
406 * @param tag the input BCP47 language tag.
407 * @param status error information if creating the Locale failed.
408 * @return the Locale for the specified BCP47 language tag.
409 * @stable ICU 63
410 */
411 static Locale U_EXPORT2 forLanguageTag(StringPiece tag, UErrorCode& status);
412
413 /**
414 * Returns a well-formed language tag for this Locale.
415 * <p>
416 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
417 * requirement will be silently omitted from the result.
418 *
419 * If this function fails, partial output may have been written to the sink.
420 *
421 * @param sink the output sink receiving the BCP47 language
422 * tag for this Locale.
423 * @param status error information if creating the language tag failed.
424 * @stable ICU 63
425 */
426 void toLanguageTag(ByteSink& sink, UErrorCode& status) const;
427
428 /**
429 * Returns a well-formed language tag for this Locale.
430 * <p>
431 * <b>Note</b>: Any locale fields which do not satisfy the BCP47 syntax
432 * requirement will be silently omitted from the result.
433 *
434 * @param status error information if creating the language tag failed.
435 * @return the BCP47 language tag for this Locale.
436 * @stable ICU 63
437 */
438 template<typename StringClass>
439 inline StringClass toLanguageTag(UErrorCode& status) const;
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 according to CLDR by calling uloc_canonicalize().
455 * @param name the locale ID to create from. Must not be nullptr.
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 /**
512 * Add the likely subtags for this Locale, per the algorithm described
513 * in the following CLDR technical report:
514 *
515 * http://www.unicode.org/reports/tr35/#Likely_Subtags
516 *
517 * If this Locale is already in the maximal form, or not valid, or there is
518 * no data available for maximization, the Locale will be unchanged.
519 *
520 * For example, "sh" cannot be maximized, since there is no
521 * reasonable maximization.
522 *
523 * Examples:
524 *
525 * "und_Zzzz" maximizes to "en_Latn_US"
526 *
527 * "en" maximizes to "en_Latn_US"
528 *
529 * "de" maximizes to "de_Latn_DE"
530 *
531 * "sr" maximizes to "sr_Cyrl_RS"
532 *
533 * "zh_Hani" maximizes to "zh_Hani_CN"
534 *
535 * @param status error information if maximizing this Locale failed.
536 * If this Locale is not well-formed, the error code is
537 * U_ILLEGAL_ARGUMENT_ERROR.
538 * @stable ICU 63
539 */
540 void addLikelySubtags(UErrorCode& status);
541
542 /**
543 * Minimize the subtags for this Locale, per the algorithm described
544 * in the following CLDR technical report:
545 *
546 * http://www.unicode.org/reports/tr35/#Likely_Subtags
547 *
548 * If this Locale is already in the minimal form, or not valid, or there is
549 * no data available for minimization, the Locale will be unchanged.
550 *
551 * Since the minimization algorithm relies on proper maximization, see the
552 * comments for addLikelySubtags for reasons why there might not be any
553 * data.
554 *
555 * Examples:
556 *
557 * "en_Latn_US" minimizes to "en"
558 *
559 * "de_Latn_US" minimizes to "de"
560 *
561 * "sr_Cyrl_RS" minimizes to "sr"
562 *
563 * "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the
564 * script, and minimizing to "zh" would imply "zh_Hans_CN".)
565 *
566 * @param status error information if maximizing this Locale failed.
567 * If this Locale is not well-formed, the error code is
568 * U_ILLEGAL_ARGUMENT_ERROR.
569 * @stable ICU 63
570 */
571 void minimizeSubtags(UErrorCode& status);
572
573 /**
574 * Canonicalize the locale ID of this object according to CLDR.
575 * @param status the status code
576 * @stable ICU 67
577 * @see createCanonical
578 */
579 void canonicalize(UErrorCode& status);
580
581 /**
582 * Gets the list of keywords for the specified locale.
583 *
584 * @param status the status code
585 * @return pointer to StringEnumeration class, or nullptr if there are no keywords.
586 * Client must dispose of it by calling delete.
587 * @see getKeywords
588 * @stable ICU 2.8
589 */
590 StringEnumeration * createKeywords(UErrorCode &status) const;
591
592 /**
593 * Gets the list of Unicode keywords for the specified locale.
594 *
595 * @param status the status code
596 * @return pointer to StringEnumeration class, or nullptr if there are no keywords.
597 * Client must dispose of it by calling delete.
598 * @see getUnicodeKeywords
599 * @stable ICU 63
600 */
601 StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
602
603 /**
604 * Gets the set of keywords for this Locale.
605 *
606 * A wrapper to call createKeywords() and write the resulting
607 * keywords as standard strings (or compatible objects) into any kind of
608 * container that can be written to by an STL style output iterator.
609 *
610 * @param iterator an STL style output iterator to write the keywords to.
611 * @param status error information if creating set of keywords failed.
612 * @stable ICU 63
613 */
614 template<typename StringClass, typename OutputIterator>
615 inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
616
617 /**
618 * Gets the set of Unicode keywords for this Locale.
619 *
620 * A wrapper to call createUnicodeKeywords() and write the resulting
621 * keywords as standard strings (or compatible objects) into any kind of
622 * container that can be written to by an STL style output iterator.
623 *
624 * @param iterator an STL style output iterator to write the keywords to.
625 * @param status error information if creating set of keywords failed.
626 * @stable ICU 63
627 */
628 template<typename StringClass, typename OutputIterator>
629 inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
630
631 /**
632 * Gets the value for a keyword.
633 *
634 * This uses legacy keyword=value pairs, like "collation=phonebook".
635 *
636 * ICU4C doesn't do automatic conversion between legacy and Unicode
637 * keywords and values in getters and setters (as opposed to ICU4J).
638 *
639 * @param keywordName name of the keyword for which we want the value. Case insensitive.
640 * @param buffer The buffer to receive the keyword value.
641 * @param bufferCapacity The capacity of receiving buffer
642 * @param status Returns any error information while performing this operation.
643 * @return the length of the keyword value
644 *
645 * @stable ICU 2.8
646 */
647 int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
648
649 /**
650 * Gets the value for a keyword.
651 *
652 * This uses legacy keyword=value pairs, like "collation=phonebook".
653 *
654 * ICU4C doesn't do automatic conversion between legacy and Unicode
655 * keywords and values in getters and setters (as opposed to ICU4J).
656 *
657 * @param keywordName name of the keyword for which we want the value.
658 * @param sink the sink to receive the keyword value.
659 * @param status error information if getting the value failed.
660 * @stable ICU 63
661 */
662 void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
663
664 /**
665 * Gets the value for a keyword.
666 *
667 * This uses legacy keyword=value pairs, like "collation=phonebook".
668 *
669 * ICU4C doesn't do automatic conversion between legacy and Unicode
670 * keywords and values in getters and setters (as opposed to ICU4J).
671 *
672 * @param keywordName name of the keyword for which we want the value.
673 * @param status error information if getting the value failed.
674 * @return the keyword value.
675 * @stable ICU 63
676 */
677 template<typename StringClass>
678 inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
679
680 /**
681 * Gets the Unicode value for a Unicode keyword.
682 *
683 * This uses Unicode key-value pairs, like "co-phonebk".
684 *
685 * ICU4C doesn't do automatic conversion between legacy and Unicode
686 * keywords and values in getters and setters (as opposed to ICU4J).
687 *
688 * @param keywordName name of the keyword for which we want the value.
689 * @param sink the sink to receive the keyword value.
690 * @param status error information if getting the value failed.
691 * @stable ICU 63
692 */
693 void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
694
695 /**
696 * Gets the Unicode value for a Unicode keyword.
697 *
698 * This uses Unicode key-value pairs, like "co-phonebk".
699 *
700 * ICU4C doesn't do automatic conversion between legacy and Unicode
701 * keywords and values in getters and setters (as opposed to ICU4J).
702 *
703 * @param keywordName name of the keyword for which we want the value.
704 * @param status error information if getting the value failed.
705 * @return the keyword value.
706 * @stable ICU 63
707 */
708 template<typename StringClass>
709 inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
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 * nullptr, 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 /**
733 * Sets or removes the value for a keyword.
734 *
735 * For removing all keywords, use getBaseName(),
736 * and construct a new Locale if it differs from getName().
737 *
738 * This uses legacy keyword=value pairs, like "collation=phonebook".
739 *
740 * ICU4C doesn't do automatic conversion between legacy and Unicode
741 * keywords and values in getters and setters (as opposed to ICU4J).
742 *
743 * @param keywordName name of the keyword to be set.
744 * @param keywordValue value of the keyword to be set. If 0-length or
745 * nullptr, will result in the keyword being removed. No error is given if
746 * that keyword does not exist.
747 * @param status Returns any error information while performing this operation.
748 * @stable ICU 63
749 */
750 void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
751
752 /**
753 * Sets or removes the Unicode value for a Unicode keyword.
754 *
755 * For removing all keywords, use getBaseName(),
756 * and construct a new Locale if it differs from getName().
757 *
758 * This uses Unicode key-value pairs, like "co-phonebk".
759 *
760 * ICU4C doesn't do automatic conversion between legacy and Unicode
761 * keywords and values in getters and setters (as opposed to ICU4J).
762 *
763 * @param keywordName name of the keyword to be set.
764 * @param keywordValue value of the keyword to be set. If 0-length or
765 * nullptr, will result in the keyword being removed. No error is given if
766 * that keyword does not exist.
767 * @param status Returns any error information while performing this operation.
768 * @stable ICU 63
769 */
770 void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
771
772 /**
773 * returns the locale's three-letter language code, as specified
774 * in ISO draft standard ISO-639-2.
775 * @return An alias to the code, or an empty string
776 * @stable ICU 2.0
777 */
778 const char * getISO3Language() const;
779
780 /**
781 * Fills in "name" with the locale's three-letter ISO-3166 country code.
782 * @return An alias to the code, or an empty string
783 * @stable ICU 2.0
784 */
785 const char * getISO3Country() const;
786
787 /**
788 * Returns the Windows LCID value corresponding to this locale.
789 * This value is stored in the resource data for the locale as a one-to-four-digit
790 * hexadecimal number. If the resource is missing, in the wrong format, or
791 * there is no Windows LCID value that corresponds to this locale, returns 0.
792 * @stable ICU 2.0
793 */
794 uint32_t getLCID() const;
795
796 /**
797 * Returns whether this locale's script is written right-to-left.
798 * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
799 * If no likely script is known, then false is returned.
800 *
801 * A script is right-to-left according to the CLDR script metadata
802 * which corresponds to whether the script's letters have Bidi_Class=R or AL.
803 *
804 * Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".
805 *
806 * @return true if the locale's script is written right-to-left
807 * @stable ICU 54
808 */
809 UBool isRightToLeft() 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 default locale. For example, if the locale's language code is
814 * "fr" and the default locale's language code is "en", this function would set
815 * dispLang to "French".
816 * @param dispLang Receives the language's display name.
817 * @return A reference to "dispLang".
818 * @stable ICU 2.0
819 */
820 UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
821
822 /**
823 * Fills in "dispLang" with the name of this locale's language in a format suitable for
824 * user display in the locale specified by "displayLocale". For example, if the locale's
825 * language code is "en" and displayLocale's language code is "fr", this function would set
826 * dispLang to "Anglais".
827 * @param displayLocale Specifies the locale to be used to display the name. In other words,
828 * if the locale's language code is "en", passing Locale::getFrench() for
829 * displayLocale would result in "Anglais", while passing Locale::getGerman()
830 * for displayLocale would result in "Englisch".
831 * @param dispLang Receives the language's display name.
832 * @return A reference to "dispLang".
833 * @stable ICU 2.0
834 */
835 UnicodeString& getDisplayLanguage( const Locale& displayLocale,
836 UnicodeString& dispLang) const;
837
838 /**
839 * Fills in "dispScript" with the name of this locale's script in a format suitable
840 * for user display in the default locale. For example, if the locale's script code
841 * is "LATN" and the default locale's language code is "en", this function would set
842 * dispScript to "Latin".
843 * @param dispScript Receives the scripts's display name.
844 * @return A reference to "dispScript".
845 * @stable ICU 2.8
846 */
847 UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
848
849 /**
850 * Fills in "dispScript" with the name of this locale's country in a format suitable
851 * for user display in the locale specified by "displayLocale". For example, if the locale's
852 * script code is "LATN" and displayLocale's language code is "en", this function would set
853 * dispScript to "Latin".
854 * @param displayLocale Specifies the locale to be used to display the name. In other
855 * words, if the locale's script code is "LATN", passing
856 * Locale::getFrench() for displayLocale would result in "", while
857 * passing Locale::getGerman() for displayLocale would result in
858 * "".
859 * @param dispScript Receives the scripts's display name.
860 * @return A reference to "dispScript".
861 * @stable ICU 2.8
862 */
863 UnicodeString& getDisplayScript( const Locale& displayLocale,
864 UnicodeString& dispScript) 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 default locale. For example, if the locale's country code
869 * is "FR" and the default locale's language code is "en", this function would set
870 * dispCountry to "France".
871 * @param dispCountry Receives the country's display name.
872 * @return A reference to "dispCountry".
873 * @stable ICU 2.0
874 */
875 UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
876
877 /**
878 * Fills in "dispCountry" with the name of this locale's country in a format suitable
879 * for user display in the locale specified by "displayLocale". For example, if the locale's
880 * country code is "US" and displayLocale's language code is "fr", this function would set
881 * dispCountry to "États-Unis".
882 * @param displayLocale Specifies the locale to be used to display the name. In other
883 * words, if the locale's country code is "US", passing
884 * Locale::getFrench() for displayLocale would result in "États-Unis", while
885 * passing Locale::getGerman() for displayLocale would result in
886 * "Vereinigte Staaten".
887 * @param dispCountry Receives the country's display name.
888 * @return A reference to "dispCountry".
889 * @stable ICU 2.0
890 */
891 UnicodeString& getDisplayCountry( const Locale& displayLocale,
892 UnicodeString& dispCountry) const;
893
894 /**
895 * Fills in "dispVar" with the name of this locale's variant code in a format suitable
896 * for user display in the default locale.
897 * @param dispVar Receives the variant's name.
898 * @return A reference to "dispVar".
899 * @stable ICU 2.0
900 */
901 UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
902
903 /**
904 * Fills in "dispVar" with the name of this locale's variant code in a format
905 * suitable for user display in the locale specified by "displayLocale".
906 * @param displayLocale Specifies the locale to be used to display the name.
907 * @param dispVar Receives the variant's display name.
908 * @return A reference to "dispVar".
909 * @stable ICU 2.0
910 */
911 UnicodeString& getDisplayVariant( const Locale& displayLocale,
912 UnicodeString& dispVar) const;
913
914 /**
915 * Fills in "name" with the name of this locale in a format suitable for user display
916 * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(),
917 * and getDisplayVariant() to do its work, and outputs the display name in the format
918 * "language (country[,variant])". For example, if the default locale is en_US, then
919 * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
920 * would be "Spanish (Mexico,Traditional)".
921 * @param name Receives the locale's display name.
922 * @return A reference to "name".
923 * @stable ICU 2.0
924 */
925 UnicodeString& getDisplayName( UnicodeString& name) const;
926
927 /**
928 * Fills in "name" with the name of this locale in a format suitable for user display
929 * in the locale specified by "displayLocale". This function uses getDisplayLanguage(),
930 * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
931 * name in the format "language (country[,variant])". For example, if displayLocale is
932 * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's
933 * display name would be "norvégien (Norvège,NY)".
934 * @param displayLocale Specifies the locale to be used to display the name.
935 * @param name Receives the locale's display name.
936 * @return A reference to "name".
937 * @stable ICU 2.0
938 */
939 UnicodeString& getDisplayName( const Locale& displayLocale,
940 UnicodeString& name) const;
941
942 /**
943 * Generates a hash code for the locale.
944 * @stable ICU 2.0
945 */
946 int32_t hashCode() const;
947
948 /**
949 * Sets the locale to bogus
950 * A bogus locale represents a non-existing locale associated
951 * with services that can be instantiated from non-locale data
952 * in addition to locale (for example, collation can be
953 * instantiated from a locale and from a rule set).
954 * @stable ICU 2.1
955 */
956 void setToBogus();
957
958 /**
959 * Gets the bogus state. Locale object can be bogus if it doesn't exist
960 * @return false if it is a real locale, true if it is a bogus locale
961 * @stable ICU 2.1
962 */
963 inline UBool isBogus() const;
964
965 /**
966 * Returns a list of all installed locales.
967 * @param count Receives the number of locales in the list.
968 * @return A pointer to an array of Locale objects. This array is the list
969 * of all locales with installed resource files. The called does NOT
970 * get ownership of this list, and must NOT delete it.
971 * @stable ICU 2.0
972 */
973 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
974
975 /**
976 * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a
977 * pointer to an array of pointers to arrays of char. All of these pointers are
978 * owned by ICU-- do not delete them, and do not write through them. The array is
979 * terminated with a null pointer.
980 * @return a list of all available country codes
981 * @stable ICU 2.0
982 */
983 static const char* const* U_EXPORT2 getISOCountries();
984
985 /**
986 * Returns a list of all unique language codes defined in ISO 639.
987 * They can be 2 or 3 letter codes, as defined by
988 * <a href="https://www.ietf.org/rfc/bcp/bcp47.html#section-2.2.1">
989 * BCP 47, section 2.2.1</a>. This is a pointer
990 * to an array of pointers to arrays of char. All of these pointers are owned
991 * by ICU-- do not delete them, and do not write through them. The array is
992 * terminated with a null pointer.
993 * @return a list of all available language codes
994 * @stable ICU 2.0
995 */
996 static const char* const* U_EXPORT2 getISOLanguages();
997
998 /**
999 * ICU "poor man's RTTI", returns a UClassID for this class.
1000 *
1001 * @stable ICU 2.2
1002 */
1003 static UClassID U_EXPORT2 getStaticClassID();
1004
1005 /**
1006 * ICU "poor man's RTTI", returns a UClassID for the actual class.
1007 *
1008 * @stable ICU 2.2
1009 */
1010 virtual UClassID getDynamicClassID() const override;
1011
1012 /**
1013 * A Locale iterator interface similar to a Java Iterator<Locale>.
1014 * @stable ICU 65
1015 */
1016 class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1017 public:
1018 /** @stable ICU 65 */
1019 virtual ~Iterator();
1020
1021 /**
1022 * @return true if next() can be called again.
1023 * @stable ICU 65
1024 */
1025 virtual UBool hasNext() const = 0;
1026
1027 /**
1028 * @return the next locale.
1029 * @stable ICU 65
1030 */
1031 virtual const Locale &next() = 0;
1032 };
1033
1034 /**
1035 * A generic Locale iterator implementation over Locale input iterators.
1036 * @stable ICU 65
1037 */
1038 template<typename Iter>
1039 class RangeIterator : public Iterator, public UMemory {
1040 public:
1041 /**
1042 * Constructs an iterator from a begin/end range.
1043 * Each of the iterator parameter values must be an
1044 * input iterator whose value is convertible to const Locale &.
1045 *
1046 * @param begin Start of range.
1047 * @param end Exclusive end of range.
1048 * @stable ICU 65
1049 */
RangeIterator(Iter begin,Iter end)1050 RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1051
1052 /**
1053 * @return true if next() can be called again.
1054 * @stable ICU 65
1055 */
hasNext()1056 UBool hasNext() const override { return it_ != end_; }
1057
1058 /**
1059 * @return the next locale.
1060 * @stable ICU 65
1061 */
next()1062 const Locale &next() override { return *it_++; }
1063
1064 private:
1065 Iter it_;
1066 const Iter end_;
1067 };
1068
1069 /**
1070 * A generic Locale iterator implementation over Locale input iterators.
1071 * Calls the converter to convert each *begin to a const Locale &.
1072 * @stable ICU 65
1073 */
1074 template<typename Iter, typename Conv>
1075 class ConvertingIterator : public Iterator, public UMemory {
1076 public:
1077 /**
1078 * Constructs an iterator from a begin/end range.
1079 * Each of the iterator parameter values must be an
1080 * input iterator whose value the converter converts to const Locale &.
1081 *
1082 * @param begin Start of range.
1083 * @param end Exclusive end of range.
1084 * @param converter Converter from *begin to const Locale & or compatible.
1085 * @stable ICU 65
1086 */
ConvertingIterator(Iter begin,Iter end,Conv converter)1087 ConvertingIterator(Iter begin, Iter end, Conv converter) :
1088 it_(begin), end_(end), converter_(converter) {}
1089
1090 /**
1091 * @return true if next() can be called again.
1092 * @stable ICU 65
1093 */
hasNext()1094 UBool hasNext() const override { return it_ != end_; }
1095
1096 /**
1097 * @return the next locale.
1098 * @stable ICU 65
1099 */
next()1100 const Locale &next() override { return converter_(*it_++); }
1101
1102 private:
1103 Iter it_;
1104 const Iter end_;
1105 Conv converter_;
1106 };
1107
1108 protected: /* only protected for testing purposes. DO NOT USE. */
1109 #ifndef U_HIDE_INTERNAL_API
1110 /**
1111 * Set this from a single POSIX style locale string.
1112 * @internal
1113 */
1114 void setFromPOSIXID(const char *posixID);
1115 /**
1116 * Minimize the subtags for this Locale, per the algorithm described
1117 * @param favorScript favor to keep script if true, to keep region if false.
1118 * @param status error information if maximizing this Locale failed.
1119 * If this Locale is not well-formed, the error code is
1120 * U_ILLEGAL_ARGUMENT_ERROR.
1121 * @internal
1122 */
1123 void minimizeSubtags(bool favorScript, UErrorCode& status);
1124 #endif /* U_HIDE_INTERNAL_API */
1125
1126 private:
1127 /**
1128 * Initialize the locale object with a new name.
1129 * Was deprecated - used in implementation - moved internal
1130 *
1131 * @param cLocaleID The new locale name.
1132 * @param canonicalize whether to call uloc_canonicalize on cLocaleID
1133 */
1134 Locale& init(const char* cLocaleID, UBool canonicalize);
1135
1136 /*
1137 * Internal constructor to allow construction of a locale object with
1138 * NO side effects. (Default constructor tries to get
1139 * the default locale.)
1140 */
1141 enum ELocaleType {
1142 eBOGUS
1143 };
1144 Locale(ELocaleType);
1145
1146 /**
1147 * Initialize the locale cache for commonly used locales
1148 */
1149 static Locale* getLocaleCache();
1150
1151 char language[ULOC_LANG_CAPACITY];
1152 char script[ULOC_SCRIPT_CAPACITY];
1153 char country[ULOC_COUNTRY_CAPACITY];
1154 int32_t variantBegin;
1155 char* fullName;
1156 char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1157 // name without keywords
1158 char* baseName;
1159 void initBaseName(UErrorCode& status);
1160
1161 UBool fIsBogus;
1162
1163 static const Locale &getLocale(int locid);
1164
1165 /**
1166 * A friend to allow the default locale to be set by either the C or C++ API.
1167 * @internal (private)
1168 */
1169 friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1170
1171 /**
1172 * @internal (private)
1173 */
1174 friend void U_CALLCONV locale_available_init();
1175 };
1176
1177 inline bool
1178 Locale::operator!=(const Locale& other) const
1179 {
1180 return !operator==(other);
1181 }
1182
1183 template<typename StringClass> inline StringClass
toLanguageTag(UErrorCode & status)1184 Locale::toLanguageTag(UErrorCode& status) const
1185 {
1186 if (U_FAILURE(status)) { return {}; }
1187 StringClass result;
1188 StringByteSink<StringClass> sink(&result);
1189 toLanguageTag(sink, status);
1190 return result;
1191 }
1192
1193 inline const char *
getCountry()1194 Locale::getCountry() const
1195 {
1196 return country;
1197 }
1198
1199 inline const char *
getLanguage()1200 Locale::getLanguage() const
1201 {
1202 return language;
1203 }
1204
1205 inline const char *
getScript()1206 Locale::getScript() const
1207 {
1208 return script;
1209 }
1210
1211 inline const char *
getVariant()1212 Locale::getVariant() const
1213 {
1214 return fIsBogus ? "" : &baseName[variantBegin];
1215 }
1216
1217 inline const char *
getName()1218 Locale::getName() const
1219 {
1220 return fullName;
1221 }
1222
1223 template<typename StringClass, typename OutputIterator> inline void
getKeywords(OutputIterator iterator,UErrorCode & status)1224 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1225 {
1226 if (U_FAILURE(status)) { return; }
1227 LocalPointer<StringEnumeration> keys(createKeywords(status));
1228 if (U_FAILURE(status) || keys.isNull()) {
1229 return;
1230 }
1231 for (;;) {
1232 int32_t resultLength;
1233 const char* buffer = keys->next(&resultLength, status);
1234 if (U_FAILURE(status) || buffer == nullptr) {
1235 return;
1236 }
1237 *iterator++ = StringClass(buffer, resultLength);
1238 }
1239 }
1240
1241 template<typename StringClass, typename OutputIterator> inline void
getUnicodeKeywords(OutputIterator iterator,UErrorCode & status)1242 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1243 {
1244 if (U_FAILURE(status)) { return; }
1245 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1246 if (U_FAILURE(status) || keys.isNull()) {
1247 return;
1248 }
1249 for (;;) {
1250 int32_t resultLength;
1251 const char* buffer = keys->next(&resultLength, status);
1252 if (U_FAILURE(status) || buffer == nullptr) {
1253 return;
1254 }
1255 *iterator++ = StringClass(buffer, resultLength);
1256 }
1257 }
1258
1259 template<typename StringClass> inline StringClass
getKeywordValue(StringPiece keywordName,UErrorCode & status)1260 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1261 {
1262 if (U_FAILURE(status)) { return {}; }
1263 StringClass result;
1264 StringByteSink<StringClass> sink(&result);
1265 getKeywordValue(keywordName, sink, status);
1266 return result;
1267 }
1268
1269 template<typename StringClass> inline StringClass
getUnicodeKeywordValue(StringPiece keywordName,UErrorCode & status)1270 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1271 {
1272 if (U_FAILURE(status)) { return {}; }
1273 StringClass result;
1274 StringByteSink<StringClass> sink(&result);
1275 getUnicodeKeywordValue(keywordName, sink, status);
1276 return result;
1277 }
1278
1279 inline UBool
isBogus()1280 Locale::isBogus() const {
1281 return fIsBogus;
1282 }
1283
1284 U_NAMESPACE_END
1285
1286 #endif /* U_SHOW_CPLUSPLUS_API */
1287
1288 #endif
1289