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 according to CLDR 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 #ifndef U_HIDE_DRAFT_API
571 /**
572 * Canonicalize the locale ID of this object according to CLDR.
573 * @param status the status code
574 * @draft ICU 67
575 * @see createCanonical
576 */
577 void canonicalize(UErrorCode& status);
578 #endif // U_HIDE_DRAFT_API
579
580 /**
581 * Gets the list of keywords for the specified locale.
582 *
583 * @param status the status code
584 * @return pointer to StringEnumeration class, or NULL if there are no keywords.
585 * Client must dispose of it by calling delete.
586 * @see getKeywords
587 * @stable ICU 2.8
588 */
589 StringEnumeration * createKeywords(UErrorCode &status) const;
590
591 /**
592 * Gets the list of Unicode keywords for the specified locale.
593 *
594 * @param status the status code
595 * @return pointer to StringEnumeration class, or NULL if there are no keywords.
596 * Client must dispose of it by calling delete.
597 * @see getUnicodeKeywords
598 * @stable ICU 63
599 */
600 StringEnumeration * createUnicodeKeywords(UErrorCode &status) const;
601
602 /**
603 * Gets the set of keywords for this Locale.
604 *
605 * A wrapper to call createKeywords() and write the resulting
606 * keywords as standard strings (or compatible objects) into any kind of
607 * container that can be written to by an STL style output iterator.
608 *
609 * @param iterator an STL style output iterator to write the keywords to.
610 * @param status error information if creating set of keywords failed.
611 * @stable ICU 63
612 */
613 template<typename StringClass, typename OutputIterator>
614 inline void getKeywords(OutputIterator iterator, UErrorCode& status) const;
615
616 /**
617 * Gets the set of Unicode keywords for this Locale.
618 *
619 * A wrapper to call createUnicodeKeywords() and write the resulting
620 * keywords as standard strings (or compatible objects) into any kind of
621 * container that can be written to by an STL style output iterator.
622 *
623 * @param iterator an STL style output iterator to write the keywords to.
624 * @param status error information if creating set of keywords failed.
625 * @stable ICU 63
626 */
627 template<typename StringClass, typename OutputIterator>
628 inline void getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const;
629
630 /**
631 * Gets the value for a keyword.
632 *
633 * This uses legacy keyword=value pairs, like "collation=phonebook".
634 *
635 * ICU4C doesn't do automatic conversion between legacy and Unicode
636 * keywords and values in getters and setters (as opposed to ICU4J).
637 *
638 * @param keywordName name of the keyword for which we want the value. Case insensitive.
639 * @param buffer The buffer to receive the keyword value.
640 * @param bufferCapacity The capacity of receiving buffer
641 * @param status Returns any error information while performing this operation.
642 * @return the length of the keyword value
643 *
644 * @stable ICU 2.8
645 */
646 int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
647
648 /**
649 * Gets the value for a keyword.
650 *
651 * This uses legacy keyword=value pairs, like "collation=phonebook".
652 *
653 * ICU4C doesn't do automatic conversion between legacy and Unicode
654 * keywords and values in getters and setters (as opposed to ICU4J).
655 *
656 * @param keywordName name of the keyword for which we want the value.
657 * @param sink the sink to receive the keyword value.
658 * @param status error information if getting the value failed.
659 * @stable ICU 63
660 */
661 void getKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
662
663 /**
664 * Gets the value for a keyword.
665 *
666 * This uses legacy keyword=value pairs, like "collation=phonebook".
667 *
668 * ICU4C doesn't do automatic conversion between legacy and Unicode
669 * keywords and values in getters and setters (as opposed to ICU4J).
670 *
671 * @param keywordName name of the keyword for which we want the value.
672 * @param status error information if getting the value failed.
673 * @return the keyword value.
674 * @stable ICU 63
675 */
676 template<typename StringClass>
677 inline StringClass getKeywordValue(StringPiece keywordName, UErrorCode& status) const;
678
679 /**
680 * Gets the Unicode value for a Unicode keyword.
681 *
682 * This uses Unicode key-value pairs, like "co-phonebk".
683 *
684 * ICU4C doesn't do automatic conversion between legacy and Unicode
685 * keywords and values in getters and setters (as opposed to ICU4J).
686 *
687 * @param keywordName name of the keyword for which we want the value.
688 * @param sink the sink to receive the keyword value.
689 * @param status error information if getting the value failed.
690 * @stable ICU 63
691 */
692 void getUnicodeKeywordValue(StringPiece keywordName, ByteSink& sink, UErrorCode& status) const;
693
694 /**
695 * Gets the Unicode value for a Unicode keyword.
696 *
697 * This uses Unicode key-value pairs, like "co-phonebk".
698 *
699 * ICU4C doesn't do automatic conversion between legacy and Unicode
700 * keywords and values in getters and setters (as opposed to ICU4J).
701 *
702 * @param keywordName name of the keyword for which we want the value.
703 * @param status error information if getting the value failed.
704 * @return the keyword value.
705 * @stable ICU 63
706 */
707 template<typename StringClass>
708 inline StringClass getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const;
709
710 /**
711 * Sets or removes the value for a keyword.
712 *
713 * For removing all keywords, use getBaseName(),
714 * and construct a new Locale if it differs from getName().
715 *
716 * This uses legacy keyword=value pairs, like "collation=phonebook".
717 *
718 * ICU4C doesn't do automatic conversion between legacy and Unicode
719 * keywords and values in getters and setters (as opposed to ICU4J).
720 *
721 * @param keywordName name of the keyword to be set. Case insensitive.
722 * @param keywordValue value of the keyword to be set. If 0-length or
723 * NULL, will result in the keyword being removed. No error is given if
724 * that keyword does not exist.
725 * @param status Returns any error information while performing this operation.
726 *
727 * @stable ICU 49
728 */
729 void setKeywordValue(const char* keywordName, const char* keywordValue, UErrorCode &status);
730
731 /**
732 * Sets or removes the value for a keyword.
733 *
734 * For removing all keywords, use getBaseName(),
735 * and construct a new Locale if it differs from getName().
736 *
737 * This uses legacy keyword=value pairs, like "collation=phonebook".
738 *
739 * ICU4C doesn't do automatic conversion between legacy and Unicode
740 * keywords and values in getters and setters (as opposed to ICU4J).
741 *
742 * @param keywordName name of the keyword to be set.
743 * @param keywordValue value of the keyword to be set. If 0-length or
744 * NULL, will result in the keyword being removed. No error is given if
745 * that keyword does not exist.
746 * @param status Returns any error information while performing this operation.
747 * @stable ICU 63
748 */
749 void setKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
750
751 /**
752 * Sets or removes the Unicode value for a Unicode keyword.
753 *
754 * For removing all keywords, use getBaseName(),
755 * and construct a new Locale if it differs from getName().
756 *
757 * This uses Unicode key-value pairs, like "co-phonebk".
758 *
759 * ICU4C doesn't do automatic conversion between legacy and Unicode
760 * keywords and values in getters and setters (as opposed to ICU4J).
761 *
762 * @param keywordName name of the keyword to be set.
763 * @param keywordValue value of the keyword to be set. If 0-length or
764 * NULL, will result in the keyword being removed. No error is given if
765 * that keyword does not exist.
766 * @param status Returns any error information while performing this operation.
767 * @stable ICU 63
768 */
769 void setUnicodeKeywordValue(StringPiece keywordName, StringPiece keywordValue, UErrorCode& status);
770
771 /**
772 * returns the locale's three-letter language code, as specified
773 * in ISO draft standard ISO-639-2.
774 * @return An alias to the code, or an empty string
775 * @stable ICU 2.0
776 */
777 const char * getISO3Language() const;
778
779 /**
780 * Fills in "name" with the locale's three-letter ISO-3166 country code.
781 * @return An alias to the code, or an empty string
782 * @stable ICU 2.0
783 */
784 const char * getISO3Country() const;
785
786 /**
787 * Returns the Windows LCID value corresponding to this locale.
788 * This value is stored in the resource data for the locale as a one-to-four-digit
789 * hexadecimal number. If the resource is missing, in the wrong format, or
790 * there is no Windows LCID value that corresponds to this locale, returns 0.
791 * @stable ICU 2.0
792 */
793 uint32_t getLCID(void) const;
794
795 /**
796 * Returns whether this locale's script is written right-to-left.
797 * If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags().
798 * If no likely script is known, then FALSE is returned.
799 *
800 * A script is right-to-left according to the CLDR script metadata
801 * which corresponds to whether the script's letters have Bidi_Class=R or AL.
802 *
803 * Returns TRUE for "ar" and "en-Hebr", FALSE for "zh" and "fa-Cyrl".
804 *
805 * @return TRUE if the locale's script is written right-to-left
806 * @stable ICU 54
807 */
808 UBool isRightToLeft() const;
809
810 /**
811 * Fills in "dispLang" with the name of this locale's language in a format suitable for
812 * user display in the default locale. For example, if the locale's language code is
813 * "fr" and the default locale's language code is "en", this function would set
814 * dispLang to "French".
815 * @param dispLang Receives the language's display name.
816 * @return A reference to "dispLang".
817 * @stable ICU 2.0
818 */
819 UnicodeString& getDisplayLanguage(UnicodeString& dispLang) const;
820
821 /**
822 * Fills in "dispLang" with the name of this locale's language in a format suitable for
823 * user display in the locale specified by "displayLocale". For example, if the locale's
824 * language code is "en" and displayLocale's language code is "fr", this function would set
825 * dispLang to "Anglais".
826 * @param displayLocale Specifies the locale to be used to display the name. In other words,
827 * if the locale's language code is "en", passing Locale::getFrench() for
828 * displayLocale would result in "Anglais", while passing Locale::getGerman()
829 * for displayLocale would result in "Englisch".
830 * @param dispLang Receives the language's display name.
831 * @return A reference to "dispLang".
832 * @stable ICU 2.0
833 */
834 UnicodeString& getDisplayLanguage( const Locale& displayLocale,
835 UnicodeString& dispLang) const;
836
837 /**
838 * Fills in "dispScript" with the name of this locale's script in a format suitable
839 * for user display in the default locale. For example, if the locale's script code
840 * is "LATN" and the default locale's language code is "en", this function would set
841 * dispScript to "Latin".
842 * @param dispScript Receives the scripts's display name.
843 * @return A reference to "dispScript".
844 * @stable ICU 2.8
845 */
846 UnicodeString& getDisplayScript( UnicodeString& dispScript) const;
847
848 /**
849 * Fills in "dispScript" with the name of this locale's country in a format suitable
850 * for user display in the locale specified by "displayLocale". For example, if the locale's
851 * script code is "LATN" and displayLocale's language code is "en", this function would set
852 * dispScript to "Latin".
853 * @param displayLocale Specifies the locale to be used to display the name. In other
854 * words, if the locale's script code is "LATN", passing
855 * Locale::getFrench() for displayLocale would result in "", while
856 * passing Locale::getGerman() for displayLocale would result in
857 * "".
858 * @param dispScript Receives the scripts's display name.
859 * @return A reference to "dispScript".
860 * @stable ICU 2.8
861 */
862 UnicodeString& getDisplayScript( const Locale& displayLocale,
863 UnicodeString& dispScript) const;
864
865 /**
866 * Fills in "dispCountry" with the name of this locale's country in a format suitable
867 * for user display in the default locale. For example, if the locale's country code
868 * is "FR" and the default locale's language code is "en", this function would set
869 * dispCountry to "France".
870 * @param dispCountry Receives the country's display name.
871 * @return A reference to "dispCountry".
872 * @stable ICU 2.0
873 */
874 UnicodeString& getDisplayCountry( UnicodeString& dispCountry) const;
875
876 /**
877 * Fills in "dispCountry" with the name of this locale's country in a format suitable
878 * for user display in the locale specified by "displayLocale". For example, if the locale's
879 * country code is "US" and displayLocale's language code is "fr", this function would set
880 * dispCountry to "États-Unis".
881 * @param displayLocale Specifies the locale to be used to display the name. In other
882 * words, if the locale's country code is "US", passing
883 * Locale::getFrench() for displayLocale would result in "États-Unis", while
884 * passing Locale::getGerman() for displayLocale would result in
885 * "Vereinigte Staaten".
886 * @param dispCountry Receives the country's display name.
887 * @return A reference to "dispCountry".
888 * @stable ICU 2.0
889 */
890 UnicodeString& getDisplayCountry( const Locale& displayLocale,
891 UnicodeString& dispCountry) const;
892
893 /**
894 * Fills in "dispVar" with the name of this locale's variant code in a format suitable
895 * for user display in the default locale.
896 * @param dispVar Receives the variant's name.
897 * @return A reference to "dispVar".
898 * @stable ICU 2.0
899 */
900 UnicodeString& getDisplayVariant( UnicodeString& dispVar) const;
901
902 /**
903 * Fills in "dispVar" with the name of this locale's variant code in a format
904 * suitable for user display in the locale specified by "displayLocale".
905 * @param displayLocale Specifies the locale to be used to display the name.
906 * @param dispVar Receives the variant's display name.
907 * @return A reference to "dispVar".
908 * @stable ICU 2.0
909 */
910 UnicodeString& getDisplayVariant( const Locale& displayLocale,
911 UnicodeString& dispVar) const;
912
913 /**
914 * Fills in "name" with the name of this locale in a format suitable for user display
915 * in the default locale. This function uses getDisplayLanguage(), getDisplayCountry(),
916 * and getDisplayVariant() to do its work, and outputs the display name in the format
917 * "language (country[,variant])". For example, if the default locale is en_US, then
918 * fr_FR's display name would be "French (France)", and es_MX_Traditional's display name
919 * would be "Spanish (Mexico,Traditional)".
920 * @param name Receives the locale's display name.
921 * @return A reference to "name".
922 * @stable ICU 2.0
923 */
924 UnicodeString& getDisplayName( UnicodeString& name) const;
925
926 /**
927 * Fills in "name" with the name of this locale in a format suitable for user display
928 * in the locale specified by "displayLocale". This function uses getDisplayLanguage(),
929 * getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display
930 * name in the format "language (country[,variant])". For example, if displayLocale is
931 * fr_FR, then en_US's display name would be "Anglais (États-Unis)", and no_NO_NY's
932 * display name would be "norvégien (Norvège,NY)".
933 * @param displayLocale Specifies the locale to be used to display the name.
934 * @param name Receives the locale's display name.
935 * @return A reference to "name".
936 * @stable ICU 2.0
937 */
938 UnicodeString& getDisplayName( const Locale& displayLocale,
939 UnicodeString& name) const;
940
941 /**
942 * Generates a hash code for the locale.
943 * @stable ICU 2.0
944 */
945 int32_t hashCode(void) const;
946
947 /**
948 * Sets the locale to bogus
949 * A bogus locale represents a non-existing locale associated
950 * with services that can be instantiated from non-locale data
951 * in addition to locale (for example, collation can be
952 * instantiated from a locale and from a rule set).
953 * @stable ICU 2.1
954 */
955 void setToBogus();
956
957 /**
958 * Gets the bogus state. Locale object can be bogus if it doesn't exist
959 * @return FALSE if it is a real locale, TRUE if it is a bogus locale
960 * @stable ICU 2.1
961 */
962 inline UBool isBogus(void) const;
963
964 /**
965 * Returns a list of all installed locales.
966 * @param count Receives the number of locales in the list.
967 * @return A pointer to an array of Locale objects. This array is the list
968 * of all locales with installed resource files. The called does NOT
969 * get ownership of this list, and must NOT delete it.
970 * @stable ICU 2.0
971 */
972 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
973
974 /**
975 * Gets a list of all available 2-letter country codes defined in ISO 3166. This is a
976 * pointer to an array of pointers to arrays of char. All of these pointers are
977 * owned 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 country codes
980 * @stable ICU 2.0
981 */
982 static const char* const* U_EXPORT2 getISOCountries();
983
984 /**
985 * Gets a list of all available language codes defined in ISO 639. This is a pointer
986 * to an array of pointers to arrays of char. All of these pointers are owned
987 * by ICU-- do not delete them, and do not write through them. The array is
988 * terminated with a null pointer.
989 * @return a list of all available language codes
990 * @stable ICU 2.0
991 */
992 static const char* const* U_EXPORT2 getISOLanguages();
993
994 /**
995 * ICU "poor man's RTTI", returns a UClassID for this class.
996 *
997 * @stable ICU 2.2
998 */
999 static UClassID U_EXPORT2 getStaticClassID();
1000
1001 /**
1002 * ICU "poor man's RTTI", returns a UClassID for the actual class.
1003 *
1004 * @stable ICU 2.2
1005 */
1006 virtual UClassID getDynamicClassID() const;
1007
1008 #ifndef U_HIDE_DRAFT_API
1009 /**
1010 * A Locale iterator interface similar to a Java Iterator<Locale>.
1011 * @draft ICU 65
1012 */
1013 class U_COMMON_API Iterator /* not : public UObject because this is an interface/mixin class */ {
1014 public:
1015 /** @draft ICU 65 */
1016 virtual ~Iterator();
1017
1018 /**
1019 * @return TRUE if next() can be called again.
1020 * @draft ICU 65
1021 */
1022 virtual UBool hasNext() const = 0;
1023
1024 /**
1025 * @return the next locale.
1026 * @draft ICU 65
1027 */
1028 virtual const Locale &next() = 0;
1029 };
1030
1031 /**
1032 * A generic Locale iterator implementation over Locale input iterators.
1033 * @draft ICU 65
1034 */
1035 template<typename Iter>
1036 class RangeIterator : public Iterator, public UMemory {
1037 public:
1038 /**
1039 * Constructs an iterator from a begin/end range.
1040 * Each of the iterator parameter values must be an
1041 * input iterator whose value is convertible to const Locale &.
1042 *
1043 * @param begin Start of range.
1044 * @param end Exclusive end of range.
1045 * @draft ICU 65
1046 */
RangeIterator(Iter begin,Iter end)1047 RangeIterator(Iter begin, Iter end) : it_(begin), end_(end) {}
1048
1049 /**
1050 * @return TRUE if next() can be called again.
1051 * @draft ICU 65
1052 */
hasNext()1053 UBool hasNext() const override { return it_ != end_; }
1054
1055 /**
1056 * @return the next locale.
1057 * @draft ICU 65
1058 */
next()1059 const Locale &next() override { return *it_++; }
1060
1061 private:
1062 Iter it_;
1063 const Iter end_;
1064 };
1065
1066 /**
1067 * A generic Locale iterator implementation over Locale input iterators.
1068 * Calls the converter to convert each *begin to a const Locale &.
1069 * @draft ICU 65
1070 */
1071 template<typename Iter, typename Conv>
1072 class ConvertingIterator : public Iterator, public UMemory {
1073 public:
1074 /**
1075 * Constructs an iterator from a begin/end range.
1076 * Each of the iterator parameter values must be an
1077 * input iterator whose value the converter converts to const Locale &.
1078 *
1079 * @param begin Start of range.
1080 * @param end Exclusive end of range.
1081 * @param converter Converter from *begin to const Locale & or compatible.
1082 * @draft ICU 65
1083 */
ConvertingIterator(Iter begin,Iter end,Conv converter)1084 ConvertingIterator(Iter begin, Iter end, Conv converter) :
1085 it_(begin), end_(end), converter_(converter) {}
1086
1087 /**
1088 * @return TRUE if next() can be called again.
1089 * @draft ICU 65
1090 */
hasNext()1091 UBool hasNext() const override { return it_ != end_; }
1092
1093 /**
1094 * @return the next locale.
1095 * @draft ICU 65
1096 */
next()1097 const Locale &next() override { return converter_(*it_++); }
1098
1099 private:
1100 Iter it_;
1101 const Iter end_;
1102 Conv converter_;
1103 };
1104 #endif // U_HIDE_DRAFT_API
1105
1106 protected: /* only protected for testing purposes. DO NOT USE. */
1107 #ifndef U_HIDE_INTERNAL_API
1108 /**
1109 * Set this from a single POSIX style locale string.
1110 * @internal
1111 */
1112 void setFromPOSIXID(const char *posixID);
1113 #endif /* U_HIDE_INTERNAL_API */
1114
1115 private:
1116 /**
1117 * Initialize the locale object with a new name.
1118 * Was deprecated - used in implementation - moved internal
1119 *
1120 * @param cLocaleID The new locale name.
1121 * @param canonicalize whether to call uloc_canonicalize on cLocaleID
1122 */
1123 Locale& init(const char* cLocaleID, UBool canonicalize);
1124
1125 /*
1126 * Internal constructor to allow construction of a locale object with
1127 * NO side effects. (Default constructor tries to get
1128 * the default locale.)
1129 */
1130 enum ELocaleType {
1131 eBOGUS
1132 };
1133 Locale(ELocaleType);
1134
1135 /**
1136 * Initialize the locale cache for commonly used locales
1137 */
1138 static Locale *getLocaleCache(void);
1139
1140 char language[ULOC_LANG_CAPACITY];
1141 char script[ULOC_SCRIPT_CAPACITY];
1142 char country[ULOC_COUNTRY_CAPACITY];
1143 int32_t variantBegin;
1144 char* fullName;
1145 char fullNameBuffer[ULOC_FULLNAME_CAPACITY];
1146 // name without keywords
1147 char* baseName;
1148 void initBaseName(UErrorCode& status);
1149
1150 UBool fIsBogus;
1151
1152 static const Locale &getLocale(int locid);
1153
1154 /**
1155 * A friend to allow the default locale to be set by either the C or C++ API.
1156 * @internal (private)
1157 */
1158 friend Locale *locale_set_default_internal(const char *, UErrorCode& status);
1159
1160 /**
1161 * @internal (private)
1162 */
1163 friend void U_CALLCONV locale_available_init();
1164 };
1165
1166 inline UBool
1167 Locale::operator!=(const Locale& other) const
1168 {
1169 return !operator==(other);
1170 }
1171
1172 template<typename StringClass> inline StringClass
toLanguageTag(UErrorCode & status)1173 Locale::toLanguageTag(UErrorCode& status) const
1174 {
1175 StringClass result;
1176 StringByteSink<StringClass> sink(&result);
1177 toLanguageTag(sink, status);
1178 return result;
1179 }
1180
1181 inline const char *
getCountry()1182 Locale::getCountry() const
1183 {
1184 return country;
1185 }
1186
1187 inline const char *
getLanguage()1188 Locale::getLanguage() const
1189 {
1190 return language;
1191 }
1192
1193 inline const char *
getScript()1194 Locale::getScript() const
1195 {
1196 return script;
1197 }
1198
1199 inline const char *
getVariant()1200 Locale::getVariant() const
1201 {
1202 return &baseName[variantBegin];
1203 }
1204
1205 inline const char *
getName()1206 Locale::getName() const
1207 {
1208 return fullName;
1209 }
1210
1211 template<typename StringClass, typename OutputIterator> inline void
getKeywords(OutputIterator iterator,UErrorCode & status)1212 Locale::getKeywords(OutputIterator iterator, UErrorCode& status) const
1213 {
1214 LocalPointer<StringEnumeration> keys(createKeywords(status));
1215 if (U_FAILURE(status) || keys.isNull()) {
1216 return;
1217 }
1218 for (;;) {
1219 int32_t resultLength;
1220 const char* buffer = keys->next(&resultLength, status);
1221 if (U_FAILURE(status) || buffer == nullptr) {
1222 return;
1223 }
1224 *iterator++ = StringClass(buffer, resultLength);
1225 }
1226 }
1227
1228 template<typename StringClass, typename OutputIterator> inline void
getUnicodeKeywords(OutputIterator iterator,UErrorCode & status)1229 Locale::getUnicodeKeywords(OutputIterator iterator, UErrorCode& status) const
1230 {
1231 LocalPointer<StringEnumeration> keys(createUnicodeKeywords(status));
1232 if (U_FAILURE(status) || keys.isNull()) {
1233 return;
1234 }
1235 for (;;) {
1236 int32_t resultLength;
1237 const char* buffer = keys->next(&resultLength, status);
1238 if (U_FAILURE(status) || buffer == nullptr) {
1239 return;
1240 }
1241 *iterator++ = StringClass(buffer, resultLength);
1242 }
1243 }
1244
1245 template<typename StringClass> inline StringClass
getKeywordValue(StringPiece keywordName,UErrorCode & status)1246 Locale::getKeywordValue(StringPiece keywordName, UErrorCode& status) const
1247 {
1248 StringClass result;
1249 StringByteSink<StringClass> sink(&result);
1250 getKeywordValue(keywordName, sink, status);
1251 return result;
1252 }
1253
1254 template<typename StringClass> inline StringClass
getUnicodeKeywordValue(StringPiece keywordName,UErrorCode & status)1255 Locale::getUnicodeKeywordValue(StringPiece keywordName, UErrorCode& status) const
1256 {
1257 StringClass result;
1258 StringByteSink<StringClass> sink(&result);
1259 getUnicodeKeywordValue(keywordName, sink, status);
1260 return result;
1261 }
1262
1263 inline UBool
isBogus(void)1264 Locale::isBogus(void) const {
1265 return fIsBogus;
1266 }
1267
1268 U_NAMESPACE_END
1269
1270 #endif /* U_SHOW_CPLUSPLUS_API */
1271
1272 #endif
1273