Loading...
Searching...
No Matches
icu::Locale Class Reference

A `Locale` object represents a specific geographical, political, or cultural region. More...

`#include <locid.h>`

Inheritance diagram for icu::Locale:

## Data Structures

class | Iterator
| A Locale iterator interface similar to a Java Iterator<Locale>. More...
class | RangeIterator
| A generic Locale iterator implementation over Locale input iterators. More...
class | ConvertingIterator
| A generic Locale iterator implementation over Locale input iterators. More...

## Public Member Functions

U_COMMON_API | Locale ()
| Construct a default locale object, a Locale for the default locale ID.
U_COMMON_API | Locale (const char *language, const char *country=nullptr, const char *variant=nullptr, const char *keywordsAndValues=nullptr)
| Construct a locale from language, country, variant.
U_COMMON_API | Locale (const Locale &other)
| Initializes a Locale object from another Locale object.
U_COMMON_API | Locale (Locale &&other) noexcept
| Move constructor; might leave source in bogus state.
virtual U_COMMON_API | ~Locale ()
| Destructor.
U_COMMON_API Locale & | operator= (const Locale &other)
| Replaces the entire contents of *this with the specified value.
U_COMMON_API Locale & | operator= (Locale &&other) noexcept
| Move assignment operator; might leave source in bogus state.
U_COMMON_API bool | operator== (const Locale &other) const
| Checks if two locale keys are the same.
U_COMMON_API bool | operator!= (const Locale &other) const
| Checks if two locale keys are not the same.
U_COMMON_API Locale * | clone () const
| Clone this object.
U_COMMON_API void | toLanguageTag (ByteSink &sink, UErrorCode &status) const
| Returns a well-formed language tag for this Locale.
template<typename StringClass>
StringClass | toLanguageTag (UErrorCode &status) const
| Returns a well-formed language tag for this Locale.
U_COMMON_API const char * | getLanguage () const
| Returns the locale's ISO-639 language code.
U_COMMON_API const char * | getScript () const
| Returns the locale's ISO-15924 abbreviation script code.
U_COMMON_API const char * | getCountry () const
| Returns the locale's ISO-3166 country code.
U_COMMON_API const char * | getVariant () const
| Returns the locale's variant code.
U_COMMON_API const char * | getName () const
| Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.
U_COMMON_API const char * | getBaseName () const
| Returns the programmatic name of the entire locale as getName() would return, but without keywords.
U_COMMON_API void | addLikelySubtags (UErrorCode &status)
| Add the likely subtags for this Locale, per the algorithm described in the following CLDR technical report:
U_COMMON_API void | minimizeSubtags (UErrorCode &status)
| Minimize the subtags for this Locale, per the algorithm described in the following CLDR technical report:
U_COMMON_API void | canonicalize (UErrorCode &status)
| Canonicalize the locale ID of this object according to CLDR.
U_COMMON_API StringEnumeration * | createKeywords (UErrorCode &status) const
| Gets the list of keywords for the specified locale.
U_COMMON_API StringEnumeration * | createUnicodeKeywords (UErrorCode &status) const
| Gets the list of Unicode keywords for the specified locale.
template<typename StringClass, typename OutputIterator>
void | getKeywords (OutputIterator iterator, UErrorCode &status) const
| Gets the set of keywords for this Locale.
template<typename StringClass, typename OutputIterator>
void | getUnicodeKeywords (OutputIterator iterator, UErrorCode &status) const
| Gets the set of Unicode keywords for this Locale.
U_COMMON_API int32_t | getKeywordValue (const char *keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const
| Gets the value for a keyword.
U_COMMON_API void | getKeywordValue (StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
| Gets the value for a keyword.
template<typename StringClass>
StringClass | getKeywordValue (StringPiece keywordName, UErrorCode &status) const
| Gets the value for a keyword.
U_COMMON_API void | getUnicodeKeywordValue (StringPiece keywordName, ByteSink &sink, UErrorCode &status) const
| Gets the Unicode value for a Unicode keyword.
template<typename StringClass>
StringClass | getUnicodeKeywordValue (StringPiece keywordName, UErrorCode &status) const
| Gets the Unicode value for a Unicode keyword.
U_COMMON_API void | setKeywordValue (const char *keywordName, const char *keywordValue, UErrorCode &status)
| Sets or removes the value for a keyword.
U_COMMON_API void | setKeywordValue (StringPiece keywordName, StringPiece keywordValue, UErrorCode &status)
| Sets or removes the value for a keyword.
U_COMMON_API void | setUnicodeKeywordValue (StringPiece keywordName, StringPiece keywordValue, UErrorCode &status)
| Sets or removes the Unicode value for a Unicode keyword.
U_COMMON_API const char * | getISO3Language () const
| returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.
U_COMMON_API const char * | getISO3Country () const
| Fills in "name" with the locale's three-letter ISO-3166 country code.
U_COMMON_API uint32_t | getLCID () const
| Returns the Windows LCID value corresponding to this locale.
U_COMMON_API UBool | isRightToLeft () const
| Returns whether this locale's script is written right-to-left.
U_COMMON_API UnicodeString & | getDisplayLanguage (UnicodeString &dispLang) const
| Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the default locale.
U_COMMON_API UnicodeString & | getDisplayLanguage (const Locale &displayLocale, UnicodeString &dispLang) const
| Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the locale specified by "displayLocale".
U_COMMON_API UnicodeString & | getDisplayScript (UnicodeString &dispScript) const
| Fills in "dispScript" with the name of this locale's script in a format suitable for user display in the default locale.
U_COMMON_API UnicodeString & | getDisplayScript (const Locale &displayLocale, UnicodeString &dispScript) const
| Fills in "dispScript" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".
U_COMMON_API UnicodeString & | getDisplayCountry (UnicodeString &dispCountry) const
| Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the default locale.
U_COMMON_API UnicodeString & | getDisplayCountry (const Locale &displayLocale, UnicodeString &dispCountry) const
| Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".
U_COMMON_API UnicodeString & | getDisplayVariant (UnicodeString &dispVar) const
| Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the default locale.
U_COMMON_API UnicodeString & | getDisplayVariant (const Locale &displayLocale, UnicodeString &dispVar) const
| Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the locale specified by "displayLocale".
U_COMMON_API UnicodeString & | getDisplayName (UnicodeString &name) const
| Fills in "name" with the name of this locale in a format suitable for user display in the default locale.
U_COMMON_API UnicodeString & | getDisplayName (const Locale &displayLocale, UnicodeString &name) const
| Fills in "name" with the name of this locale in a format suitable for user display in the locale specified by "displayLocale".
U_COMMON_API int32_t | hashCode () const
| Generates a hash code for the locale.
U_COMMON_API void | setToBogus ()
| Sets the locale to bogus A bogus locale represents a non-existing locale associated with services that can be instantiated from non-locale data in addition to locale (for example, collation can be instantiated from a locale and from a rule set).
U_COMMON_API UBool | isBogus () const
| Gets the bogus state.
virtual U_COMMON_API UClassID | getDynamicClassID () const override
| ICU "poor man's RTTI", returns a UClassID for the actual class.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## Static Public Member Functions

static U_COMMON_API const Locale & | getRoot ()
| Useful constant for the Root locale.
static U_COMMON_API const Locale & | getEnglish ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getFrench ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getGerman ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getItalian ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getJapanese ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getKorean ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getChinese ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getSimplifiedChinese ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getTraditionalChinese ()
| Useful constant for this language.
static U_COMMON_API const Locale & | getFrance ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getGermany ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getItaly ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getJapan ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getKorea ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getChina ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getPRC ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getTaiwan ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getUK ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getUS ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getCanada ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getCanadaFrench ()
| Useful constant for this country/region.
static U_COMMON_API const Locale & | getDefault ()
| Common methods of getting the current default Locale.
static U_COMMON_API void | setDefault (const Locale &newLocale, UErrorCode &success)
| Sets the default.
static U_COMMON_API Locale | forLanguageTag (StringPiece tag, UErrorCode &status)
| Returns a Locale for the specified BCP47 language tag string.
static U_COMMON_API Locale | createFromName (const char *name)
| Creates a locale which has had minimal canonicalization as per uloc_getName().
static U_COMMON_API Locale | createFromName (StringPiece name)
static U_COMMON_API Locale | createCanonical (const char *name)
| Creates a locale from the given string after canonicalizing the string according to CLDR by calling uloc_canonicalize().
static U_COMMON_API const Locale * | getAvailableLocales (int32_t &count)
| Returns a list of all installed locales.
static U_COMMON_API const char *const * | getISOCountries ()
| Gets a list of all available 2-letter country codes defined in ISO 3166.
static U_COMMON_API const char *const * | getISOLanguages ()
| Returns a list of all unique language codes defined in ISO 639.
static U_COMMON_API UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.

## Protected Member Functions

U_COMMON_API void | setFromPOSIXID (const char *posixID)
| Set this from a single POSIX style locale string.
U_COMMON_API void | minimizeSubtags (bool favorScript, UErrorCode &status)
| Minimize the subtags for this Locale, per the algorithm described.

## Friends

Locale * | locale_set_default_internal (const char *, UErrorCode &status)
| A friend to allow the default locale to be set by either the C or C++ API.
void | locale_available_init ()

## Detailed Description

A `Locale` object represents a specific geographical, political, or cultural region.

An operation that requires a `Locale` to perform its task is called locale-sensitive and uses the `Locale` to tailor information for the user. For example, displaying a number is a locale-sensitive operation–the number should be formatted according to the customs/conventions of the user's native country, region, or culture.

The Locale class is not suitable for subclassing.

You can create a `Locale` object using the constructor in this class:

>           Locale( const   char*  language,
>                   const   char*  country,
>                   const   char*  variant);

The first argument to the constructors is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. You can find a full list of these codes at:
http://www.loc.gov/standards/iso639-2/

The second argument to the constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
http://www.iso.org/iso/en/prods-services/iso3166ma/index.html

The third constructor requires a third argument–the Variant. The Variant codes are vendor and browser-specific. For example, use REVISED for a language's revised script orthography, and POSIX for POSIX. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might be referenced, with "ES", "ES", "Traditional_POSIX".

Because a `Locale` object is just an identifier for a region, no validity check is performed when you construct a `Locale`. If you want to see whether particular resources are available for the `Locale` you construct, you must query those resources. For example, ask the `NumberFormat` for the locales it supports using its `getAvailableLocales` method.
Note: When you ask for a resource for a particular locale, you get back the best available match, not necessarily precisely what you asked for. For more information, look at `ResourceBundle`.

The `Locale` class provides a number of convenient constants that you can use to create `Locale` objects for commonly used locales. For example, the following refers to a `Locale` object for the United States:

>           Locale::getUS()

Once you've created a `Locale` you can query it for information about itself. Use `getCountry` to get the ISO Country Code and `getLanguage` to get the ISO Language Code. You can use `getDisplayCountry` to get the name of the country suitable for displaying to the user. Similarly, you can use `getDisplayLanguage` to get the name of the language suitable for displaying to the user. Interestingly, the `getDisplayXXX` methods are themselves locale-sensitive and have two versions: one that uses the default locale and one that takes a locale as an argument and displays the name or country in a language appropriate to that locale.

ICU provides a number of classes that perform locale-sensitive operations. For example, the `NumberFormat` class formats numbers, currency, or percentages in a locale-sensitive manner. Classes such as `NumberFormat` have a number of convenience methods for creating a default object of that type. For example, the `NumberFormat` class provides these three convenience methods for creating a default `NumberFormat` object:

>         UErrorCode success = U_ZERO_ERROR;
>         Locale myLocale;
>         NumberFormat *nf;

>         nf = NumberFormat::createInstance( success );          delete nf;
>         nf = NumberFormat::createCurrencyInstance( success );  delete nf;
>         nf = NumberFormat::createPercentInstance( success );   delete nf;

Each of these methods has two variants; one with an explicit locale and one without; the latter using the default locale.

>         nf = NumberFormat::createInstance( myLocale, success );          delete nf;
>         nf = NumberFormat::createCurrencyInstance( myLocale, success );  delete nf;
>         nf = NumberFormat::createPercentInstance( myLocale, success );   delete nf;

A `Locale` is the mechanism for identifying the kind of object (`NumberFormat`) that you would like to get. The locale is just a mechanism for identifying objects, not a container for the objects themselves.

Each class that performs locale-sensitive operations allows you to get all the available objects of that type. You can sift through these objects by language, country, or variant, and use the display names to present a menu to the user. For example, you can create a menu of all the collation objects suitable for a given language. Such classes implement these three class methods:

>           static Locale* getAvailableLocales(int32_t& numLocales)
>           static UnicodeString& getDisplayName(const Locale&  objectLocale,
>                                                const Locale&  displayLocale,
>                                                UnicodeString& displayName)
>           static UnicodeString& getDisplayName(const Locale&  objectLocale,
>                                                UnicodeString& displayName)

Stable
  ICU 2.0

See also
  ResourceBundle

Definition at line 198 of file locid.h.

## Constructor & Destructor Documentation

## Locale() [1/4]

U_COMMON_API icu::Locale::Locale | ( |  | ) |

Construct a default locale object, a Locale for the default locale ID.

See also
  getDefault
  uloc_getDefault

Stable
  ICU 2.0

References U_COMMON_API.

Referenced by clone(), createCanonical(), createFromName(), createFromName(), forLanguageTag(), getAvailableLocales(), getCanada(), getCanadaFrench(), getChina(), getChinese(), getDefault(), getDisplayCountry(), getDisplayLanguage(), getDisplayName(), getDisplayScript(), getDisplayVariant(), getEnglish(), getFrance(), getFrench(), getGerman(), getGermany(), getItalian(), getItaly(), getJapan(), getJapanese(), getKorea(), getKorean(), getPRC(), getRoot(), getSimplifiedChinese(), getTaiwan(), getTraditionalChinese(), getUK(), getUS(), Locale(), Locale(), locale_set_default_internal, minimizeSubtags(), icu::Locale::ConvertingIterator< Iter, Conv >::next(), icu::Locale::Iterator::next(), icu::Locale::RangeIterator< Iter >::next(), operator!=(), operator=(), operator=(), operator==(), and setDefault().

## Locale() [2/4]

U_COMMON_API icu::Locale::Locale | ( | const char * | language,
|  | const char * | country = nullptr,
|  | const char * | variant = nullptr,
|  | const char * | keywordsAndValues = nullptr )

Construct a locale from language, country, variant.

If an error occurs, then the constructed object will be "bogus" (isBogus() will return true).

Parameters

  language

  Lowercase two-letter or three-letter ISO-639 code. This parameter can instead be an ICU style C locale (e.g. "en_US"), but the other parameters must not be used. This parameter can be nullptr; if so, the locale is initialized to match the current default locale. (This is the same as using the default constructor.) Please note: The Java Locale class does NOT accept the form 'new Locale("en_US")' but only 'new Locale("en","US")'

  country | Uppercase two-letter ISO-3166 code. (optional)
  variant | Uppercase vendor and browser specific code. See class description. (optional)
  keywordsAndValues | A string consisting of keyword/values pairs, such as "collation=phonebook;currency=euro"

See also
  getDefault
  uloc_getDefault

Stable
  ICU 2.0

References U_COMMON_API.

## Locale() [3/4]

U_COMMON_API icu::Locale::Locale | ( | const Locale & | other | ) |

Initializes a Locale object from another Locale object.

Parameters

  other | The Locale object being copied in.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## Locale() [4/4]

U_COMMON_API icu::Locale::Locale | ( | Locale && | other | ) |

noexcept

Move constructor; might leave source in bogus state.

This locale will have the same contents that the source locale had.

Parameters

  other | The Locale object being moved in.

Stable
  ICU 63

References Locale(), and U_COMMON_API.

## ~Locale()

virtual U_COMMON_API icu::Locale::~Locale | ( |  | ) |

virtual

Destructor.

Stable
  ICU 2.0

References U_COMMON_API.

## Member Function Documentation

## addLikelySubtags()

U_COMMON_API void icu::Locale::addLikelySubtags | ( | UErrorCode & | status | ) |

Add the likely subtags for this Locale, per the algorithm described in the following CLDR technical report:

http://www.unicode.org/reports/tr35/#Likely_Subtags

If this Locale is already in the maximal form, or not valid, or there is no data available for maximization, the Locale will be unchanged.

For example, "sh" cannot be maximized, since there is no reasonable maximization.

Examples:

"und_Zzzz" maximizes to "en_Latn_US"

"en" maximizes to "en_Latn_US"

"de" maximizes to "de_Latn_DE"

"sr" maximizes to "sr_Cyrl_RS"

"zh_Hani" maximizes to "zh_Hani_CN"

Parameters

  status | error information if maximizing this Locale failed. If this Locale is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.

Stable
  ICU 63

References U_COMMON_API.

## canonicalize()

U_COMMON_API void icu::Locale::canonicalize | ( | UErrorCode & | status | ) |

Canonicalize the locale ID of this object according to CLDR.

Parameters

  status | the status code

Stable
  ICU 67

See also
  createCanonical

References U_COMMON_API.

Referenced by minimizeSubtags().

## clone()

U_COMMON_API Locale * icu::Locale::clone | ( |  | ) | const

Clone this object.

Clones can be used concurrently in multiple threads. If an error occurs, then nullptr is returned. The caller must delete the clone.

Returns
  a clone of this object

See also
  getDynamicClassID

Stable
  ICU 2.8

References Locale(), and U_COMMON_API.

## createCanonical()

U_COMMON_API Locale icu::Locale::createCanonical | ( | const char * | name | ) |

static

Creates a locale from the given string after canonicalizing the string according to CLDR by calling uloc_canonicalize().

Parameters

  name | the locale ID to create from. Must not be nullptr.

Returns
  a new locale object corresponding to the given name

Stable
  ICU 3.0

See also
  uloc_canonicalize

References Locale(), and U_COMMON_API.

## createFromName() [1/2]

U_COMMON_API Locale icu::Locale::createFromName | ( | const char * | name | ) |

static

Creates a locale which has had minimal canonicalization as per uloc_getName().

Parameters

  name | The name to create from. If name is null, the default Locale is used.

Returns
  new locale object

Stable
  ICU 2.0

See also
  uloc_getName

References Locale(), and U_COMMON_API.

## createFromName() [2/2]

U_COMMON_API Locale icu::Locale::createFromName | ( | StringPiece | name | ) |

static

Internal
  Do not use. This API is for internal use only.

References Locale(), and U_COMMON_API.

## createKeywords()

U_COMMON_API StringEnumeration * icu::Locale::createKeywords | ( | UErrorCode & | status | ) | const

Gets the list of keywords for the specified locale.

Parameters

  status | the status code

Returns
  pointer to StringEnumeration class, or nullptr if there are no keywords. Client must dispose of it by calling delete.

See also
  getKeywords

Stable
  ICU 2.8

References U_COMMON_API.

Referenced by getKeywords().

## createUnicodeKeywords()

U_COMMON_API StringEnumeration * icu::Locale::createUnicodeKeywords | ( | UErrorCode & | status | ) | const

Gets the list of Unicode keywords for the specified locale.

Parameters

  status | the status code

Returns
  pointer to StringEnumeration class, or nullptr if there are no keywords. Client must dispose of it by calling delete.

See also
  getUnicodeKeywords

Stable
  ICU 63

References getKeywords(), getUnicodeKeywords(), and U_COMMON_API.

Referenced by getUnicodeKeywords().

## forLanguageTag()

U_COMMON_API Locale icu::Locale::forLanguageTag | ( | StringPiece | tag,
|  | UErrorCode & | status )

static

Returns a Locale for the specified BCP47 language tag string.

If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored.

This implements the 'Language-Tag' production of BCP 47, and so supports legacy language tags (marked as “Type: grandfathered” in BCP 47) (regular and irregular) as well as private use language tags.

Private use tags are represented as 'x-whatever', and legacy tags are converted to their canonical replacements where they exist.

Note that a few legacy tags have no modern replacement; these will be converted using the fallback described in the first paragraph, so some information might be lost.

Parameters

  tag | the input BCP47 language tag.
  status | error information if creating the Locale failed.

Returns
  the Locale for the specified BCP47 language tag.

Stable
  ICU 63

References Locale(), and U_COMMON_API.

## getAvailableLocales()

U_COMMON_API const Locale * icu::Locale::getAvailableLocales | ( | int32_t & | count | ) |

static

Returns a list of all installed locales.

Parameters

  count | Receives the number of locales in the list.

Returns
  A pointer to an array of Locale objects. This array is the list of all locales with installed resource files. The called does NOT get ownership of this list, and must NOT delete it.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getBaseName()

U_COMMON_API const char * icu::Locale::getBaseName | ( |  | ) | const

Returns the programmatic name of the entire locale as getName() would return, but without keywords.

Returns
  A pointer to "name".

See also
  getName

Stable
  ICU 2.8

References U_COMMON_API.

## getCanada()

U_COMMON_API const Locale & icu::Locale::getCanada | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getCanadaFrench()

U_COMMON_API const Locale & icu::Locale::getCanadaFrench | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getChina()

U_COMMON_API const Locale & icu::Locale::getChina | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getChinese()

U_COMMON_API const Locale & icu::Locale::getChinese | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getCountry()

U_COMMON_API const char * icu::Locale::getCountry | ( |  | ) | const

Returns the locale's ISO-3166 country code.

Returns
  An alias to the code

Stable
  ICU 2.0

References U_COMMON_API.

## getDefault()

U_COMMON_API const Locale & icu::Locale::getDefault | ( |  | ) |

static

Common methods of getting the current default Locale.

Used for the presentation: menus, dialogs, etc. Generally set once when your applet or application is initialized, then never reset. (If you do reset the default locale, you probably want to reload your GUI, so that the change is reflected in your interface.)

More advanced programs will allow users to use different locales for different fields, e.g. in a spreadsheet.

Note that the initial setting will match the host system.

Returns
  a reference to the Locale object for the default locale ID

System
  Do not use unless you know what you are doing.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

Referenced by icu::DateFormat::createDateInstance(), icu::DateFormat::createDateTimeInstance(), icu::Calendar::createInstance(), icu::DateFormat::createTimeInstance(), icu::RuleBasedNumberFormat::getRuleSetDisplayName(), and icu::RuleBasedNumberFormat::getRuleSetDisplayName().

## getDisplayCountry() [1/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayCountry | ( | const Locale & | displayLocale,
|  | UnicodeString & | dispCountry ) const

Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".

For example, if the locale's country code is "US" and displayLocale's language code is "fr", this function would set dispCountry to "&Eacute;tats-Unis".

Parameters

  displayLocale | Specifies the locale to be used to display the name. In other words, if the locale's country code is "US", passing Locale::getFrench() for displayLocale would result in "&Eacute;tats-Unis", while passing Locale::getGerman() for displayLocale would result in "Vereinigte Staaten".
  dispCountry | Receives the country's display name.

Returns
  A reference to "dispCountry".

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getDisplayCountry() [2/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayCountry | ( | UnicodeString & | dispCountry | ) | const

Fills in "dispCountry" with the name of this locale's country in a format suitable for user display in the default locale.

For example, if the locale's country code is "FR" and the default locale's language code is "en", this function would set dispCountry to "France".

Parameters

  dispCountry | Receives the country's display name.

Returns
  A reference to "dispCountry".

Stable
  ICU 2.0

References U_COMMON_API.

## getDisplayLanguage() [1/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayLanguage | ( | const Locale & | displayLocale,
|  | UnicodeString & | dispLang ) const

Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the locale specified by "displayLocale".

For example, if the locale's language code is "en" and displayLocale's language code is "fr", this function would set dispLang to "Anglais".

Parameters

  displayLocale | Specifies the locale to be used to display the name. In other words, if the locale's language code is "en", passing Locale::getFrench() for displayLocale would result in "Anglais", while passing Locale::getGerman() for displayLocale would result in "Englisch".
  dispLang | Receives the language's display name.

Returns
  A reference to "dispLang".

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getDisplayLanguage() [2/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayLanguage | ( | UnicodeString & | dispLang | ) | const

Fills in "dispLang" with the name of this locale's language in a format suitable for user display in the default locale.

For example, if the locale's language code is "fr" and the default locale's language code is "en", this function would set dispLang to "French".

Parameters

  dispLang | Receives the language's display name.

Returns
  A reference to "dispLang".

Stable
  ICU 2.0

References U_COMMON_API.

## getDisplayName() [1/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayName | ( | const Locale & | displayLocale,
|  | UnicodeString & | name ) const

Fills in "name" with the name of this locale in a format suitable for user display in the locale specified by "displayLocale".

This function uses getDisplayLanguage(), getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display name in the format "language (country[,variant])". For example, if displayLocale is fr_FR, then en_US's display name would be "Anglais (&Eacute;tats-Unis)", and no_NO_NY's display name would be "norv&eacute;gien (Norv&egrave;ge,NY)".

Parameters

  displayLocale | Specifies the locale to be used to display the name.
  name | Receives the locale's display name.

Returns
  A reference to "name".

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getDisplayName() [2/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayName | ( | UnicodeString & | name | ) | const

Fills in "name" with the name of this locale in a format suitable for user display in the default locale.

This function uses getDisplayLanguage(), getDisplayCountry(), and getDisplayVariant() to do its work, and outputs the display name in the format "language (country[,variant])". For example, if the default locale is en_US, then fr_FR's display name would be "French (France)", and es_MX_Traditional's display name would be "Spanish (Mexico,Traditional)".

Parameters

  name | Receives the locale's display name.

Returns
  A reference to "name".

Stable
  ICU 2.0

References U_COMMON_API.

## getDisplayScript() [1/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayScript | ( | const Locale & | displayLocale,
|  | UnicodeString & | dispScript ) const

Fills in "dispScript" with the name of this locale's country in a format suitable for user display in the locale specified by "displayLocale".

For example, if the locale's script code is "LATN" and displayLocale's language code is "en", this function would set dispScript to "Latin".

Parameters

  displayLocale | Specifies the locale to be used to display the name. In other words, if the locale's script code is "LATN", passing Locale::getFrench() for displayLocale would result in "", while passing Locale::getGerman() for displayLocale would result in "".
  dispScript | Receives the scripts's display name.

Returns
  A reference to "dispScript".

Stable
  ICU 2.8

References Locale(), and U_COMMON_API.

## getDisplayScript() [2/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayScript | ( | UnicodeString & | dispScript | ) | const

Fills in "dispScript" with the name of this locale's script in a format suitable for user display in the default locale.

For example, if the locale's script code is "LATN" and the default locale's language code is "en", this function would set dispScript to "Latin".

Parameters

  dispScript | Receives the scripts's display name.

Returns
  A reference to "dispScript".

Stable
  ICU 2.8

References U_COMMON_API.

## getDisplayVariant() [1/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayVariant | ( | const Locale & | displayLocale,
|  | UnicodeString & | dispVar ) const

Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the locale specified by "displayLocale".

Parameters

  displayLocale | Specifies the locale to be used to display the name.
  dispVar | Receives the variant's display name.

Returns
  A reference to "dispVar".

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getDisplayVariant() [2/2]

U_COMMON_API UnicodeString & icu::Locale::getDisplayVariant | ( | UnicodeString & | dispVar | ) | const

Fills in "dispVar" with the name of this locale's variant code in a format suitable for user display in the default locale.

Parameters

  dispVar | Receives the variant's name.

Returns
  A reference to "dispVar".

Stable
  ICU 2.0

References U_COMMON_API.

## getDynamicClassID()

virtual U_COMMON_API UClassID icu::Locale::getDynamicClassID | ( |  | ) | const

override virtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable
  ICU 2.2

Reimplemented from icu::UObject.

References U_COMMON_API.

## getEnglish()

U_COMMON_API const Locale & icu::Locale::getEnglish | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getFrance()

U_COMMON_API const Locale & icu::Locale::getFrance | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getFrench()

U_COMMON_API const Locale & icu::Locale::getFrench | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getGerman()

U_COMMON_API const Locale & icu::Locale::getGerman | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getGermany()

U_COMMON_API const Locale & icu::Locale::getGermany | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getISO3Country()

U_COMMON_API const char * icu::Locale::getISO3Country | ( |  | ) | const

Fills in "name" with the locale's three-letter ISO-3166 country code.

Returns
  An alias to the code, or an empty string

Stable
  ICU 2.0

References U_COMMON_API.

## getISO3Language()

U_COMMON_API const char * icu::Locale::getISO3Language | ( |  | ) | const

returns the locale's three-letter language code, as specified in ISO draft standard ISO-639-2.

Returns
  An alias to the code, or an empty string

Stable
  ICU 2.0

References U_COMMON_API.

## getISOCountries()

U_COMMON_API const char *const * icu::Locale::getISOCountries | ( |  | ) |

static

Gets a list of all available 2-letter country codes defined in ISO 3166.

This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by ICU– do not delete them, and do not write through them. The array is terminated with a null pointer.

Returns
  a list of all available country codes

Stable
  ICU 2.0

References U_COMMON_API.

## getISOLanguages()

U_COMMON_API const char *const * icu::Locale::getISOLanguages | ( |  | ) |

static

Returns a list of all unique language codes defined in ISO 639.

They can be 2 or 3 letter codes, as defined by BCP 47, section 2.2.1. This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by ICU– do not delete them, and do not write through them. The array is terminated with a null pointer.

Returns
  a list of all available language codes

Stable
  ICU 2.0

References U_COMMON_API.

## getItalian()

U_COMMON_API const Locale & icu::Locale::getItalian | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getItaly()

U_COMMON_API const Locale & icu::Locale::getItaly | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getJapan()

U_COMMON_API const Locale & icu::Locale::getJapan | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getJapanese()

U_COMMON_API const Locale & icu::Locale::getJapanese | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getKeywords()

template<typename StringClass, typename OutputIterator>

void icu::Locale::getKeywords | ( | OutputIterator | iterator,
|  | UErrorCode & | status ) const

inline

Gets the set of keywords for this Locale.

A wrapper to call createKeywords() and write the resulting keywords as standard strings (or compatible objects) into any kind of container that can be written to by an STL style output iterator.

Parameters

  iterator | an STL style output iterator to write the keywords to.
  status | error information if creating set of keywords failed.

Stable
  ICU 63

Definition at line 1341 of file locid.h.

References createKeywords(), icu::LocalPointerBase< T >::isNull(), and U_FAILURE.

Referenced by createUnicodeKeywords().

## getKeywordValue() [1/3]

U_COMMON_API int32_t icu::Locale::getKeywordValue | ( | const char * | keywordName,
|  | char * | buffer,
|  | int32_t | bufferCapacity,
|  | UErrorCode & | status ) const

Gets the value for a keyword.

This uses legacy keyword=value pairs, like "collation=phonebook".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword for which we want the value. Case insensitive.
  buffer | The buffer to receive the keyword value.
  bufferCapacity | The capacity of receiving buffer
  status | Returns any error information while performing this operation.

Returns
  the length of the keyword value

Stable
  ICU 2.8

References U_COMMON_API.

Referenced by getKeywordValue(), and getKeywordValue().

## getKeywordValue() [2/3]

U_COMMON_API void icu::Locale::getKeywordValue | ( | StringPiece | keywordName,
|  | ByteSink & | sink,
|  | UErrorCode & | status ) const

Gets the value for a keyword.

This uses legacy keyword=value pairs, like "collation=phonebook".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword for which we want the value.
  sink | the sink to receive the keyword value.
  status | error information if getting the value failed.

Stable
  ICU 63

References getKeywordValue(), and U_COMMON_API.

## getKeywordValue() [3/3]

template<typename StringClass>

StringClass icu::Locale::getKeywordValue | ( | StringPiece | keywordName,
|  | UErrorCode & | status ) const

inline

Gets the value for a keyword.

This uses legacy keyword=value pairs, like "collation=phonebook".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword for which we want the value.
  status | error information if getting the value failed.

Returns
  the keyword value.

Stable
  ICU 63

Definition at line 1377 of file locid.h.

References getKeywordValue(), and U_FAILURE.

## getKorea()

U_COMMON_API const Locale & icu::Locale::getKorea | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getKorean()

U_COMMON_API const Locale & icu::Locale::getKorean | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getLanguage()

U_COMMON_API const char * icu::Locale::getLanguage | ( |  | ) | const

Returns the locale's ISO-639 language code.

Returns
  An alias to the code

Stable
  ICU 2.0

References U_COMMON_API.

## getLCID()

U_COMMON_API uint32_t icu::Locale::getLCID | ( |  | ) | const

Returns the Windows LCID value corresponding to this locale.

This value is stored in the resource data for the locale as a one-to-four-digit hexadecimal number. If the resource is missing, in the wrong format, or there is no Windows LCID value that corresponds to this locale, returns 0.

Stable
  ICU 2.0

References U_COMMON_API.

## getName()

U_COMMON_API const char * icu::Locale::getName | ( |  | ) | const

Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.

If a field is missing, up to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"

Returns
  A pointer to "name".

Stable
  ICU 2.0

References U_COMMON_API.

## getPRC()

U_COMMON_API const Locale & icu::Locale::getPRC | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getRoot()

U_COMMON_API const Locale & icu::Locale::getRoot | ( |  | ) |

static

Useful constant for the Root locale.

Stable
  ICU 4.4

References Locale(), and U_COMMON_API.

## getScript()

U_COMMON_API const char * icu::Locale::getScript | ( |  | ) | const

Returns the locale's ISO-15924 abbreviation script code.

Returns
  An alias to the code

See also
  uscript_getShortName
  uscript_getCode

Stable
  ICU 2.8

References U_COMMON_API.

## getSimplifiedChinese()

U_COMMON_API const Locale & icu::Locale::getSimplifiedChinese | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getStaticClassID()

U_COMMON_API UClassID icu::Locale::getStaticClassID | ( |  | ) |

static

ICU "poor man's RTTI", returns a UClassID for this class.

Stable
  ICU 2.2

References U_COMMON_API.

## getTaiwan()

U_COMMON_API const Locale & icu::Locale::getTaiwan | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getTraditionalChinese()

U_COMMON_API const Locale & icu::Locale::getTraditionalChinese | ( |  | ) |

static

Useful constant for this language.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getUK()

U_COMMON_API const Locale & icu::Locale::getUK | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getUnicodeKeywords()

template<typename StringClass, typename OutputIterator>

void icu::Locale::getUnicodeKeywords | ( | OutputIterator | iterator,
|  | UErrorCode & | status ) const

inline

Gets the set of Unicode keywords for this Locale.

A wrapper to call createUnicodeKeywords() and write the resulting keywords as standard strings (or compatible objects) into any kind of container that can be written to by an STL style output iterator.

Parameters

  iterator | an STL style output iterator to write the keywords to.
  status | error information if creating set of keywords failed.

Stable
  ICU 63

Definition at line 1359 of file locid.h.

References createUnicodeKeywords(), icu::LocalPointerBase< T >::isNull(), and U_FAILURE.

Referenced by createUnicodeKeywords().

## getUnicodeKeywordValue() [1/2]

U_COMMON_API void icu::Locale::getUnicodeKeywordValue | ( | StringPiece | keywordName,
|  | ByteSink & | sink,
|  | UErrorCode & | status ) const

Gets the Unicode value for a Unicode keyword.

This uses Unicode key-value pairs, like "co-phonebk".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword for which we want the value.
  sink | the sink to receive the keyword value.
  status | error information if getting the value failed.

Stable
  ICU 63

References getUnicodeKeywordValue(), and U_COMMON_API.

Referenced by getUnicodeKeywordValue(), and getUnicodeKeywordValue().

## getUnicodeKeywordValue() [2/2]

template<typename StringClass>

StringClass icu::Locale::getUnicodeKeywordValue | ( | StringPiece | keywordName,
|  | UErrorCode & | status ) const

inline

Gets the Unicode value for a Unicode keyword.

This uses Unicode key-value pairs, like "co-phonebk".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword for which we want the value.
  status | error information if getting the value failed.

Returns
  the keyword value.

Stable
  ICU 63

Definition at line 1387 of file locid.h.

References getUnicodeKeywordValue(), and U_FAILURE.

## getUS()

U_COMMON_API const Locale & icu::Locale::getUS | ( |  | ) |

static

Useful constant for this country/region.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## getVariant()

U_COMMON_API const char * icu::Locale::getVariant | ( |  | ) | const

Returns the locale's variant code.

Returns
  An alias to the code

Stable
  ICU 2.0

References U_COMMON_API.

## hashCode()

U_COMMON_API int32_t icu::Locale::hashCode | ( |  | ) | const

Generates a hash code for the locale.

Stable
  ICU 2.0

References U_COMMON_API.

## isBogus()

U_COMMON_API UBool icu::Locale::isBogus | ( |  | ) | const

inline

Gets the bogus state.

Locale object can be bogus if it doesn't exist

Returns
  false if it is a real locale, true if it is a bogus locale

Stable
  ICU 2.1

Definition at line 1397 of file locid.h.

Referenced by setToBogus().

## isRightToLeft()

U_COMMON_API UBool icu::Locale::isRightToLeft | ( |  | ) | const

Returns whether this locale's script is written right-to-left.

If there is no script subtag, then the likely script is used, see uloc_addLikelySubtags(). If no likely script is known, then false is returned.

A script is right-to-left according to the CLDR script metadata which corresponds to whether the script's letters have Bidi_Class=R or AL.

Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".

Returns
  true if the locale's script is written right-to-left

Stable
  ICU 54

References U_COMMON_API.

## minimizeSubtags() [1/2]

U_COMMON_API void icu::Locale::minimizeSubtags | ( | bool | favorScript,
|  | UErrorCode & | status )

protected

Minimize the subtags for this Locale, per the algorithm described.

Parameters

  favorScript | favor to keep script if true, to keep region if false.
  status | error information if maximizing this Locale failed. If this Locale is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.

Internal
  Do not use. This API is for internal use only.

References canonicalize(), Locale(), and U_COMMON_API.

## minimizeSubtags() [2/2]

U_COMMON_API void icu::Locale::minimizeSubtags | ( | UErrorCode & | status | ) |

Minimize the subtags for this Locale, per the algorithm described in the following CLDR technical report:

http://www.unicode.org/reports/tr35/#Likely_Subtags

If this Locale is already in the minimal form, or not valid, or there is no data available for minimization, the Locale will be unchanged.

Since the minimization algorithm relies on proper maximization, see the comments for addLikelySubtags for reasons why there might not be any data.

Examples:

"en_Latn_US" minimizes to "en"

"de_Latn_US" minimizes to "de"

"sr_Cyrl_RS" minimizes to "sr"

"zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the script, and minimizing to "zh" would imply "zh_Hans_CN".)

Parameters

  status | error information if maximizing this Locale failed. If this Locale is not well-formed, the error code is U_ILLEGAL_ARGUMENT_ERROR.

Stable
  ICU 63

References U_COMMON_API.

## operator!=()

U_COMMON_API bool icu::Locale::operator!= | ( | const Locale & | other | ) | const

inline

Checks if two locale keys are not the same.

Parameters

  other | The locale key object to be compared with this.

Returns
  true if the two locale keys are not the same, false otherwise.

Stable
  ICU 2.0

Definition at line 1325 of file locid.h.

References Locale(), and icu::operator==().

## operator=() [1/2]

U_COMMON_API Locale & icu::Locale::operator= | ( | const Locale & | other | ) |

Replaces the entire contents of *this with the specified value.

Parameters

  other | The Locale object being copied in.

Returns
  *this

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## operator=() [2/2]

U_COMMON_API Locale & icu::Locale::operator= | ( | Locale && | other | ) |

noexcept

Move assignment operator; might leave source in bogus state.

This locale will have the same contents that the source locale had. The behavior is undefined if *this and the source are the same object.

Parameters

  other | The Locale object being moved in.

Returns
  *this

Stable
  ICU 63

References Locale(), and U_COMMON_API.

## operator==()

U_COMMON_API bool icu::Locale::operator== | ( | const Locale & | other | ) | const

Checks if two locale keys are the same.

Parameters

  other | The locale key object to be compared with this.

Returns
  true if the two locale keys are the same, false otherwise.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## setDefault()

U_COMMON_API void icu::Locale::setDefault | ( | const Locale & | newLocale,
|  | UErrorCode & | success )

static

Sets the default.

Normally set once at the beginning of a process, then never reset. setDefault() only changes ICU's default locale ID, not the default locale ID of the runtime environment.

Parameters

  newLocale | Locale to set to. If nullptr, set to the value obtained from the runtime environment.
  success | The error code.

System
  Do not use unless you know what you are doing.

Stable
  ICU 2.0

References Locale(), and U_COMMON_API.

## setFromPOSIXID()

U_COMMON_API void icu::Locale::setFromPOSIXID | ( | const char * | posixID | ) |

protected

Set this from a single POSIX style locale string.

Internal
  Do not use. This API is for internal use only.

References U_COMMON_API.

## setKeywordValue() [1/2]

U_COMMON_API void icu::Locale::setKeywordValue | ( | const char * | keywordName,
|  | const char * | keywordValue,
|  | UErrorCode & | status )

inline

Sets or removes the value for a keyword.

For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().

This uses legacy keyword=value pairs, like "collation=phonebook".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword to be set. Case insensitive.
  keywordValue | value of the keyword to be set. If 0-length or nullptr, will result in the keyword being removed. No error is given if that keyword does not exist.
  status | Returns any error information while performing this operation.

Stable
  ICU 49

Definition at line 742 of file locid.h.

References setKeywordValue(), and U_COMMON_API.

Referenced by setKeywordValue().

## setKeywordValue() [2/2]

U_COMMON_API void icu::Locale::setKeywordValue | ( | StringPiece | keywordName,
|  | StringPiece | keywordValue,
|  | UErrorCode & | status )

Sets or removes the value for a keyword.

For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().

This uses legacy keyword=value pairs, like "collation=phonebook".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword to be set.
  keywordValue | value of the keyword to be set. If 0-length or nullptr, will result in the keyword being removed. No error is given if that keyword does not exist.
  status | Returns any error information while performing this operation.

Stable
  ICU 63

References U_COMMON_API.

## setToBogus()

U_COMMON_API void icu::Locale::setToBogus | ( |  | ) |

Sets the locale to bogus A bogus locale represents a non-existing locale associated with services that can be instantiated from non-locale data in addition to locale (for example, collation can be instantiated from a locale and from a rule set).

Stable
  ICU 2.1

References isBogus(), and U_COMMON_API.

## setUnicodeKeywordValue()

U_COMMON_API void icu::Locale::setUnicodeKeywordValue | ( | StringPiece | keywordName,
|  | StringPiece | keywordValue,
|  | UErrorCode & | status )

Sets or removes the Unicode value for a Unicode keyword.

For removing all keywords, use getBaseName(), and construct a new Locale if it differs from getName().

This uses Unicode key-value pairs, like "co-phonebk".

ICU4C doesn't do automatic conversion between legacy and Unicode keywords and values in getters and setters (as opposed to ICU4J).

Parameters

  keywordName | name of the keyword to be set.
  keywordValue | value of the keyword to be set. If 0-length or nullptr, will result in the keyword being removed. No error is given if that keyword does not exist.
  status | Returns any error information while performing this operation.

Stable
  ICU 63

References U_COMMON_API.

## toLanguageTag() [1/2]

U_COMMON_API void icu::Locale::toLanguageTag | ( | ByteSink & | sink,
|  | UErrorCode & | status ) const

Returns a well-formed language tag for this Locale.

Note: Any locale fields which do not satisfy the BCP47 syntax requirement will be silently omitted from the result.

If this function fails, partial output may have been written to the sink.

Parameters

  sink | the output sink receiving the BCP47 language tag for this Locale.
  status | error information if creating the language tag failed.

Stable
  ICU 63

References toLanguageTag(), and U_COMMON_API.

Referenced by toLanguageTag(), and toLanguageTag().

## toLanguageTag() [2/2]

template<typename StringClass>

StringClass icu::Locale::toLanguageTag | ( | UErrorCode & | status | ) | const

inline

Returns a well-formed language tag for this Locale.

Note: Any locale fields which do not satisfy the BCP47 syntax requirement will be silently omitted from the result.

Parameters

  status | error information if creating the language tag failed.

Returns
  the BCP47 language tag for this Locale.

Stable
  ICU 63

Definition at line 1331 of file locid.h.

References toLanguageTag(), and U_FAILURE.

## Friends And Related Symbol Documentation

## locale_available_init

void locale_available_init | ( |  | ) |

friend

Internal
  Do not use. This API is for internal use only.

References locale_available_init, U_CALLCONV, and U_COMMON_API.

Referenced by locale_available_init.

The documentation for this class was generated from the following file:

- common/unicode/locid.h