Class ULocale
- java.lang.Object
-
- com.ibm.icu.util.ULocale
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<ULocale>
public final class ULocale extends java.lang.Object implements java.io.Serializable, java.lang.Comparable<ULocale>
. A class analogous toLocale
that provides additional support for ICU protocol. In ICU 3.0 this class is enhanced to support RFC 3066 language identifiers.Many classes and services in ICU follow a factory idiom, in which a factory method or object responds to a client request with an object. The request includes a locale (the requested locale), and the returned object is constructed using data for that locale. The system may lack data for the requested locale, in which case the locale fallback mechanism will be invoked until a populated locale is found (the valid locale). Furthermore, even when a populated locale is found (the valid locale), further fallback may be required to reach a locale containing the specific data required by the service (the actual locale).
ULocale performs 'normalization' and 'canonicalization' of locale ids. Normalization 'cleans up' ICU locale ids as follows:
- language, script, country, variant, and keywords are properly cased
(lower, title, upper, upper, and lower case respectively) - hyphens used as separators are converted to underscores
- three-letter language and country ids are converted to two-letter equivalents where available
- surrounding spaces are removed from keywords and values
- if there are multiple keywords, they are put in sorted order
- POSIX ids are converted to ICU format IDs
- Legacy language tags (marked as “Type: grandfathered” in BCP 47) are converted to ICU standard form
canonicalize
can be called to convert the id to canonical form, or thecanonicalInstance
factory method can be called.This class provides selectors
VALID_LOCALE
andACTUAL_LOCALE
intended for use in methods named getLocale(). These methods exist in several ICU classes, includingCalendar
,Currency
,UFormat
,BreakIterator
,Collator
,DateFormatSymbols
, andDecimalFormatSymbols
and their subclasses, if any. Once an object of one of these classes has been created, getLocale() may be called on it to determine the valid and actual locale arrived at during the object's construction.Note: The actual locale is returned correctly, but the valid locale is not, in most cases.
- Author:
- weiv, Alan Liu, Ram Viswanadha
- See Also:
Locale
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ULocale.AvailableType
static class
ULocale.Builder
Builder
is used to build instances ofULocale
from values configured by the setters.static class
ULocale.Category
Enum for locale categories.static class
ULocale.Minimize
Deprecated.This API is ICU internal only.static class
ULocale.Type
Opaque selector enum for getLocale().
-
Field Summary
Fields Modifier and Type Field Description static ULocale.Type
ACTUAL_LOCALE
Selector for getLocale() indicating the locale of the resource containing the data.static ULocale
CANADA
Useful constant for country/region.static ULocale
CANADA_FRENCH
Useful constant for country/region.static ULocale
CHINA
Useful constant for country/region.static ULocale
CHINESE
Useful constant for language.static ULocale
ENGLISH
Useful constant for language.static ULocale
FRANCE
Useful constant for country/region.static ULocale
FRENCH
Useful constant for language.static ULocale
GERMAN
Useful constant for language.static ULocale
GERMANY
Useful constant for country/region.static ULocale
ITALIAN
Useful constant for language.static ULocale
ITALY
Useful constant for country/region.static ULocale
JAPAN
Useful constant for country/region.static ULocale
JAPANESE
Useful constant for language.static ULocale
KOREA
Useful constant for country/region.static ULocale
KOREAN
Useful constant for language.static ULocale
PRC
Useful constant for country/region.static char
PRIVATE_USE_EXTENSION
The key for the private use locale extension ('x').static ULocale
ROOT
The root ULocale.static ULocale
SIMPLIFIED_CHINESE
Useful constant for language.static ULocale
TAIWAN
Useful constant for country/region.static ULocale
TRADITIONAL_CHINESE
Useful constant for language.static ULocale
UK
Useful constant for country/region.static char
UNICODE_LOCALE_EXTENSION
The key for Unicode locale extension ('u').static ULocale
US
Useful constant for country/region.static ULocale.Type
VALID_LOCALE
Selector for getLocale() indicating the most specific locale for which any data exists.
-
Constructor Summary
Constructors Constructor Description ULocale(java.lang.String localeID)
Constructs a ULocale from a RFC 3066 locale ID.ULocale(java.lang.String a, java.lang.String b)
Convenience overload of ULocale(String, String, String) for compatibility with java.util.Locale.ULocale(java.lang.String a, java.lang.String b, java.lang.String c)
Constructs a ULocale from a localeID constructed from the three 'fields' a, b, and c.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static ULocale
acceptLanguage(ULocale[] acceptLanguageList, boolean[] fallback)
Based on an ordered array of acceptable locales, determine an available locale for the user.static ULocale
acceptLanguage(ULocale[] acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)
Based on a list of acceptable locales, determine an available locale for the user.static ULocale
acceptLanguage(java.lang.String acceptLanguageList, boolean[] fallback)
Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.static ULocale
acceptLanguage(java.lang.String acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)
Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.static ULocale
addLikelySubtags(ULocale loc)
Adds the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags If the provided ULocale instance is already in the maximal form, or there is no data available available for maximization, it will be returned.static java.lang.String
canonicalize(java.lang.String localeID)
Returns the canonical name according to CLDR for the specified locale ID.java.lang.Object
clone()
This is for compatibility with Locale-- in actuality, since ULocale is immutable, there is no reason to clone it, so this API returns 'this'.int
compareTo(ULocale other)
Compares two ULocale for ordering.static ULocale
createCanonical(ULocale locale)
Creates a ULocale from the locale by first canonicalizing the locale according to CLDR.static ULocale
createCanonical(java.lang.String nonCanonicalID)
Creates a ULocale from the id by first canonicalizing the id according to CLDR.boolean
equals(java.lang.Object obj)
Returns true if the other object is another ULocale with the same full name.static ULocale
forLanguageTag(java.lang.String languageTag)
Returns a locale for the specified IETF BCP 47 language tag string.static ULocale
forLocale(java.util.Locale loc)
Returns a ULocale object for aLocale
.static ULocale[]
getAvailableLocales()
Unlike the Locale API, this returns an array ofULocale
, notLocale
.static java.util.Collection<ULocale>
getAvailableLocalesByType(ULocale.AvailableType type)
Returns a list of all installed locales according to the specified type.java.lang.String
getBaseName()
Returns the (normalized) base name for this locale, likegetName()
, but without keywords.static java.lang.String
getBaseName(java.lang.String localeID)
Returns the (normalized) base name for the specified locale, likegetName(String)
, but without keywords.java.lang.String
getCharacterOrientation()
Returns this locale's layout orientation for characters.java.lang.String
getCountry()
Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.static java.lang.String
getCountry(java.lang.String localeID)
Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.static ULocale
getDefault()
Returns the current default ULocale.static ULocale
getDefault(ULocale.Category category)
Returns the current default ULocale for the specified category.java.lang.String
getDisplayCountry()
Returns this locale's country localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayCountry(ULocale displayLocale)
Returns this locale's country localized for display in the provided locale.static java.lang.String
getDisplayCountry(java.lang.String localeID, ULocale displayLocale)
Returns a locale's country localized for display in the provided locale.static java.lang.String
getDisplayCountry(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's country localized for display in the provided locale.static java.lang.String
getDisplayKeyword(java.lang.String keyword)
Returns a keyword localized for display in the defaultDISPLAY
locale.static java.lang.String
getDisplayKeyword(java.lang.String keyword, ULocale displayLocale)
Returns a keyword localized for display in the specified locale.static java.lang.String
getDisplayKeyword(java.lang.String keyword, java.lang.String displayLocaleID)
Returns a keyword localized for display in the specified locale.java.lang.String
getDisplayKeywordValue(java.lang.String keyword)
Returns a keyword value localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayKeywordValue(java.lang.String keyword, ULocale displayLocale)
Returns a keyword value localized for display in the specified locale.static java.lang.String
getDisplayKeywordValue(java.lang.String localeID, java.lang.String keyword, ULocale displayLocale)
Returns a keyword value localized for display in the specified locale.static java.lang.String
getDisplayKeywordValue(java.lang.String localeID, java.lang.String keyword, java.lang.String displayLocaleID)
Returns a keyword value localized for display in the specified locale.java.lang.String
getDisplayLanguage()
Returns this locale's language localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayLanguage(ULocale displayLocale)
Returns this locale's language localized for display in the provided locale.static java.lang.String
getDisplayLanguage(java.lang.String localeID, ULocale displayLocale)
Returns a locale's language localized for display in the provided locale.static java.lang.String
getDisplayLanguage(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's language localized for display in the provided locale.java.lang.String
getDisplayLanguageWithDialect()
Returns this locale's language localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayLanguageWithDialect(ULocale displayLocale)
Returns this locale's language localized for display in the provided locale.static java.lang.String
getDisplayLanguageWithDialect(java.lang.String localeID, ULocale displayLocale)
Returns a locale's language localized for display in the provided locale.static java.lang.String
getDisplayLanguageWithDialect(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's language localized for display in the provided locale.java.lang.String
getDisplayName()
Returns this locale name localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayName(ULocale displayLocale)
Returns this locale name localized for display in the provided locale.static java.lang.String
getDisplayName(java.lang.String localeID, ULocale displayLocale)
Returns the locale ID localized for display in the provided locale.static java.lang.String
getDisplayName(java.lang.String localeID, java.lang.String displayLocaleID)
Returns the locale ID localized for display in the provided locale.java.lang.String
getDisplayNameWithDialect()
Returns this locale name localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayNameWithDialect(ULocale displayLocale)
Returns this locale name localized for display in the provided locale.static java.lang.String
getDisplayNameWithDialect(java.lang.String localeID, ULocale displayLocale)
Returns the locale ID localized for display in the provided locale.static java.lang.String
getDisplayNameWithDialect(java.lang.String localeID, java.lang.String displayLocaleID)
Returns the locale ID localized for display in the provided locale.java.lang.String
getDisplayScript()
Returns this locale's script localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayScript(ULocale displayLocale)
Returns this locale's script localized for display in the provided locale.static java.lang.String
getDisplayScript(java.lang.String localeID, ULocale displayLocale)
Returns a locale's script localized for display in the provided locale.static java.lang.String
getDisplayScript(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's script localized for display in the provided locale.java.lang.String
getDisplayScriptInContext()
Deprecated.This API is ICU internal only.java.lang.String
getDisplayScriptInContext(ULocale displayLocale)
Deprecated.This API is ICU internal only.static java.lang.String
getDisplayScriptInContext(java.lang.String localeID, ULocale displayLocale)
Deprecated.This API is ICU internal only.static java.lang.String
getDisplayScriptInContext(java.lang.String localeID, java.lang.String displayLocaleID)
Deprecated.This API is ICU internal only.java.lang.String
getDisplayVariant()
Returns this locale's variant localized for display in the defaultDISPLAY
locale.java.lang.String
getDisplayVariant(ULocale displayLocale)
Returns this locale's variant localized for display in the provided locale.static java.lang.String
getDisplayVariant(java.lang.String localeID, ULocale displayLocale)
Returns a locale's variant localized for display in the provided locale.static java.lang.String
getDisplayVariant(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's variant localized for display in the provided locale.java.lang.String
getExtension(char key)
Returns the extension (or private use) value associated with the specified key, or null if there is no extension associated with the key.java.util.Set<java.lang.Character>
getExtensionKeys()
Returns the set of extension keys associated with this locale, or the empty set if it has no extensions.ULocale
getFallback()
Returns the fallback locale for this locale.static java.lang.String
getFallback(java.lang.String localeID)
Returns the fallback locale for the specified locale, which might be the empty string.java.lang.String
getISO3Country()
Returns a three-letter abbreviation for this locale's country/region.static java.lang.String
getISO3Country(java.lang.String localeID)
Returns a three-letter abbreviation for this locale's country/region.java.lang.String
getISO3Language()
Returns a three-letter abbreviation for this locale's language.static java.lang.String
getISO3Language(java.lang.String localeID)
Returns a three-letter abbreviation for this locale's language.static java.lang.String[]
getISOCountries()
Returns a list of all 2-letter country codes defined in ISO 3166.static java.lang.String[]
getISOLanguages()
Returns a list of all 2-letter language codes defined in ISO 639.java.util.Iterator<java.lang.String>
getKeywords()
Returns an iterator over keywords for this locale.static java.util.Iterator<java.lang.String>
getKeywords(java.lang.String localeID)
Returns an iterator over keywords for the specified locale.java.lang.String
getKeywordValue(java.lang.String keywordName)
Returns the value for a keyword in this locale.static java.lang.String
getKeywordValue(java.lang.String localeID, java.lang.String keywordName)
Returns the value for a keyword in the specified locale.java.lang.String
getLanguage()
Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.static java.lang.String
getLanguage(java.lang.String localeID)
Returns the language code for the locale ID, which will either be the empty string or a lowercase ISO 639 code.java.lang.String
getLineOrientation()
Returns this locale's layout orientation for lines.java.lang.String
getName()
Returns the (normalized) full name for this locale.static java.lang.String
getName(java.lang.String localeID)
Returns the (normalized) full name for the specified locale.static java.lang.String
getRegionForSupplementalData(ULocale locale, boolean inferRegion)
Deprecated.This API is ICU internal only.java.lang.String
getScript()
Returns the script code for this locale, which might be the empty string.static java.lang.String
getScript(java.lang.String localeID)
Returns the script code for the specified locale, which might be the empty string.java.util.Set<java.lang.String>
getUnicodeLocaleAttributes()
Returns the set of unicode locale attributes associated with this locale, or the empty set if it has no attributes.java.util.Set<java.lang.String>
getUnicodeLocaleKeys()
Returns the set of Unicode locale keys defined by this locale, or the empty set if this locale has none.java.lang.String
getUnicodeLocaleType(java.lang.String key)
Returns the Unicode locale type associated with the specified Unicode locale key for this locale.java.lang.String
getVariant()
Returns the variant code for this locale, which might be the empty string.static java.lang.String
getVariant(java.lang.String localeID)
Returns the variant code for the specified locale, which might be the empty string.int
hashCode()
Returns the hashCode.boolean
isRightToLeft()
Returns whether this locale's script is written right-to-left.static ULocale
minimizeSubtags(ULocale loc)
Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags If the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned.static ULocale
minimizeSubtags(ULocale loc, ULocale.Minimize fieldToFavor)
Deprecated.This API is ICU internal only.static void
setDefault(ULocale newLocale)
Sets the default ULocale.static void
setDefault(ULocale.Category category, ULocale newLocale)
Sets the defaultULocale
for the specifiedCategory
.ULocale
setKeywordValue(java.lang.String keyword, java.lang.String value)
Given a keyword and a value, return a new locale with an updated keyword and value.static java.lang.String
setKeywordValue(java.lang.String localeID, java.lang.String keyword, java.lang.String value)
Given a locale id, a keyword, and a value, return a new locale id with an updated keyword and value.java.lang.String
toLanguageTag()
Returns a well-formed IETF BCP 47 language tag representing this locale.static java.lang.String
toLegacyKey(java.lang.String keyword)
Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key.static java.lang.String
toLegacyType(java.lang.String keyword, java.lang.String value)
Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type.java.util.Locale
toLocale()
Converts this ULocale object to aLocale
.java.lang.String
toString()
Returns a string representation of this object.static java.lang.String
toUnicodeLocaleKey(java.lang.String keyword)
Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key.static java.lang.String
toUnicodeLocaleType(java.lang.String keyword, java.lang.String value)
Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category).
-
-
-
Field Detail
-
ENGLISH
public static final ULocale ENGLISH
Useful constant for language.
-
FRENCH
public static final ULocale FRENCH
Useful constant for language.
-
GERMAN
public static final ULocale GERMAN
Useful constant for language.
-
ITALIAN
public static final ULocale ITALIAN
Useful constant for language.
-
JAPANESE
public static final ULocale JAPANESE
Useful constant for language.
-
KOREAN
public static final ULocale KOREAN
Useful constant for language.
-
CHINESE
public static final ULocale CHINESE
Useful constant for language.
-
SIMPLIFIED_CHINESE
public static final ULocale SIMPLIFIED_CHINESE
Useful constant for language.
-
TRADITIONAL_CHINESE
public static final ULocale TRADITIONAL_CHINESE
Useful constant for language.
-
FRANCE
public static final ULocale FRANCE
Useful constant for country/region.
-
GERMANY
public static final ULocale GERMANY
Useful constant for country/region.
-
ITALY
public static final ULocale ITALY
Useful constant for country/region.
-
JAPAN
public static final ULocale JAPAN
Useful constant for country/region.
-
KOREA
public static final ULocale KOREA
Useful constant for country/region.
-
CHINA
public static final ULocale CHINA
Useful constant for country/region.
-
PRC
public static final ULocale PRC
Useful constant for country/region.
-
TAIWAN
public static final ULocale TAIWAN
Useful constant for country/region.
-
UK
public static final ULocale UK
Useful constant for country/region.
-
US
public static final ULocale US
Useful constant for country/region.
-
CANADA
public static final ULocale CANADA
Useful constant for country/region.
-
CANADA_FRENCH
public static final ULocale CANADA_FRENCH
Useful constant for country/region.
-
ROOT
public static final ULocale ROOT
The root ULocale.
-
ACTUAL_LOCALE
public static ULocale.Type ACTUAL_LOCALE
Selector for getLocale() indicating the locale of the resource containing the data. This is always at or above the valid locale. If the valid locale does not contain the specific data being requested, then the actual locale will be above the valid locale. If the object was not constructed from locale data, then the valid locale is null.
-
VALID_LOCALE
public static ULocale.Type VALID_LOCALE
Selector for getLocale() indicating the most specific locale for which any data exists. This is always at or above the requested locale, and at or below the actual locale. If the requested locale does not correspond to any resource data, then the valid locale will be above the requested locale. If the object was not constructed from locale data, then the actual locale is null.Note: The valid locale will be returned correctly in ICU 3.0 or later. In ICU 2.8, it is not returned correctly.
-
PRIVATE_USE_EXTENSION
public static final char PRIVATE_USE_EXTENSION
The key for the private use locale extension ('x').
-
UNICODE_LOCALE_EXTENSION
public static final char UNICODE_LOCALE_EXTENSION
The key for Unicode locale extension ('u').
-
-
Constructor Detail
-
ULocale
public ULocale(java.lang.String localeID)
Constructs a ULocale from a RFC 3066 locale ID. The locale ID consists of optional language, script, country, and variant fields in that order, separated by underscores, followed by an optional keyword list. The script, if present, is four characters long-- this distinguishes it from a country code, which is two characters long. Other fields are distinguished by position as indicated by the underscores. The start of the keyword list is indicated by '@', and consists of two or more keyword/value pairs separated by semicolons(';').This constructor does not canonicalize the localeID. So, for example, "zh__pinyin" remains unchanged instead of converting to "zh@collation=pinyin". By default ICU only recognizes the latter as specifying pinyin collation. Use
createCanonical(java.lang.String)
orcanonicalize(java.lang.String)
if you need to canonicalize the localeID.- Parameters:
localeID
- string representation of the locale, e.g: "en_US", "sy_Cyrl_YU", "zh__pinyin", "es_ES@currency=EUR;collation=traditional"
-
ULocale
public ULocale(java.lang.String a, java.lang.String b)
Convenience overload of ULocale(String, String, String) for compatibility with java.util.Locale.- See Also:
ULocale(String, String, String)
-
ULocale
public ULocale(java.lang.String a, java.lang.String b, java.lang.String c)
Constructs a ULocale from a localeID constructed from the three 'fields' a, b, and c. These fields are concatenated using underscores to form a localeID of the form a_b_c, which is then handled like the localeID passed toULocale(String localeID)
.Java locale strings consisting of language, country, and variant will be handled by this form, since the country code (being shorter than four letters long) will not be interpreted as a script code. If a script code is present, the final argument ('c') will be interpreted as the country code. It is recommended that this constructor only be used to ease porting, and that clients instead use the single-argument constructor when constructing a ULocale from a localeID.
- Parameters:
a
- first component of the locale idb
- second component of the locale idc
- third component of the locale id- See Also:
ULocale(String)
-
-
Method Detail
-
forLocale
public static ULocale forLocale(java.util.Locale loc)
Returns a ULocale object for aLocale
. The ULocale is canonicalized.- Parameters:
loc
- aLocale
-
createCanonical
public static ULocale createCanonical(java.lang.String nonCanonicalID)
Creates a ULocale from the id by first canonicalizing the id according to CLDR.- Parameters:
nonCanonicalID
- the locale id to canonicalize- Returns:
- the locale created from the canonical version of the ID.
-
createCanonical
public static ULocale createCanonical(ULocale locale)
Creates a ULocale from the locale by first canonicalizing the locale according to CLDR.- Parameters:
locale
- the ULocale to canonicalize- Returns:
- the ULocale created from the canonical version of the ULocale.
-
toLocale
public java.util.Locale toLocale()
Converts this ULocale object to aLocale
.- Returns:
- a
Locale
that either exactly represents this object or is the closest approximation.
-
getDefault
public static ULocale getDefault()
Returns the current default ULocale.The default ULocale is synchronized to the default Java Locale. This method checks the current default Java Locale and returns an equivalent ULocale.
- Returns:
- the default ULocale.
-
setDefault
public static void setDefault(ULocale newLocale)
Sets the default ULocale. This also sets the default Locale. If the caller does not have write permission to the user.language property, a security exception will be thrown, and the default ULocale will remain unchanged.By setting the default ULocale with this method, all of the default category locales are also set to the specified default ULocale.
- Parameters:
newLocale
- the new default locale- Throws:
java.lang.SecurityException
- if a security manager exists and itscheckPermission
method doesn't allow the operation.java.lang.NullPointerException
- ifnewLocale
is null- See Also:
SecurityManager.checkPermission(java.security.Permission)
,PropertyPermission
,setDefault(Category, ULocale)
-
getDefault
public static ULocale getDefault(ULocale.Category category)
Returns the current default ULocale for the specified category.- Parameters:
category
- the category- Returns:
- the default ULocale for the specified category.
-
setDefault
public static void setDefault(ULocale.Category category, ULocale newLocale)
Sets the defaultULocale
for the specifiedCategory
. This also sets the defaultLocale
for the specifiedCategory
of the JVM. If the caller does not have write permission to the user.language property, a security exception will be thrown, and the default ULocale for the specified Category will remain unchanged.- Parameters:
category
- the specified category to set the default localenewLocale
- the new default locale- See Also:
SecurityManager.checkPermission(java.security.Permission)
,PropertyPermission
-
clone
public java.lang.Object clone()
This is for compatibility with Locale-- in actuality, since ULocale is immutable, there is no reason to clone it, so this API returns 'this'.- Overrides:
clone
in classjava.lang.Object
-
hashCode
public int hashCode()
Returns the hashCode.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a hash code value for this object.
-
equals
public boolean equals(java.lang.Object obj)
Returns true if the other object is another ULocale with the same full name. Note that since names are not canonicalized, two ULocales that function identically might not compare equal.- Overrides:
equals
in classjava.lang.Object
- Returns:
- true if this Locale is equal to the specified object.
-
compareTo
public int compareTo(ULocale other)
Compares two ULocale for ordering.Note: The order might change in future.
- Specified by:
compareTo
in interfacejava.lang.Comparable<ULocale>
- Parameters:
other
- the ULocale to be compared.- Returns:
- a negative integer, zero, or a positive integer as this ULocale is less than, equal to, or greater than the specified ULocale.
- Throws:
java.lang.NullPointerException
- ifother
is null.
-
getAvailableLocales
public static ULocale[] getAvailableLocales()
Unlike the Locale API, this returns an array ofULocale
, notLocale
.Returns a list of all installed locales. This is equivalent to calling
getAvailableLocalesByType(com.ibm.icu.util.ULocale.AvailableType)
with AvialableType.DEFAULT.
-
getAvailableLocalesByType
public static java.util.Collection<ULocale> getAvailableLocalesByType(ULocale.AvailableType type)
Returns a list of all installed locales according to the specified type.
-
getISOCountries
public static java.lang.String[] getISOCountries()
Returns a list of all 2-letter country codes defined in ISO 3166. Can be used to create Locales.
-
getISOLanguages
public static java.lang.String[] getISOLanguages()
Returns a list of all 2-letter language codes defined in ISO 639. Can be used to create Locales. [NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. The list this function returns includes both the new and the old codes for the languages whose codes have changed.]
-
getLanguage
public java.lang.String getLanguage()
Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.- See Also:
getDisplayLanguage()
,getDisplayLanguage(ULocale)
-
getLanguage
public static java.lang.String getLanguage(java.lang.String localeID)
Returns the language code for the locale ID, which will either be the empty string or a lowercase ISO 639 code.- See Also:
getDisplayLanguage()
,getDisplayLanguage(ULocale)
-
getScript
public java.lang.String getScript()
Returns the script code for this locale, which might be the empty string.- See Also:
getDisplayScript()
,getDisplayScript(ULocale)
-
getScript
public static java.lang.String getScript(java.lang.String localeID)
Returns the script code for the specified locale, which might be the empty string.- See Also:
getDisplayScript()
,getDisplayScript(ULocale)
-
getCountry
public java.lang.String getCountry()
Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.- See Also:
getDisplayCountry()
,getDisplayCountry(ULocale)
-
getCountry
public static java.lang.String getCountry(java.lang.String localeID)
Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.- Parameters:
localeID
- The locale identification string.- See Also:
getDisplayCountry()
,getDisplayCountry(ULocale)
-
getRegionForSupplementalData
@Deprecated public static java.lang.String getRegionForSupplementalData(ULocale locale, boolean inferRegion)
Deprecated.This API is ICU internal only.Get the region to use for supplemental data lookup. Uses (1) any region specified by locale tag "rg"; if none then (2) any unicode_region_tag in the locale ID; if none then (3) if inferRegion is TRUE, the region suggested by getLikelySubtags on the localeID. If no region is found, returns empty string ""- Parameters:
locale
- The locale (includes any keywords) from which to get the region to use for supplemental data.inferRegion
- If TRUE, will try to infer region from other locale elements if not found any other way.- Returns:
- String with region to use ("" if none found).
-
getVariant
public java.lang.String getVariant()
Returns the variant code for this locale, which might be the empty string.- See Also:
getDisplayVariant()
,getDisplayVariant(ULocale)
-
getVariant
public static java.lang.String getVariant(java.lang.String localeID)
Returns the variant code for the specified locale, which might be the empty string.- See Also:
getDisplayVariant()
,getDisplayVariant(ULocale)
-
getFallback
public static java.lang.String getFallback(java.lang.String localeID)
Returns the fallback locale for the specified locale, which might be the empty string.
-
getFallback
public ULocale getFallback()
Returns the fallback locale for this locale. If this locale is root, returns null.
-
getBaseName
public java.lang.String getBaseName()
Returns the (normalized) base name for this locale, likegetName()
, but without keywords.- Returns:
- the base name as a String.
-
getBaseName
public static java.lang.String getBaseName(java.lang.String localeID)
Returns the (normalized) base name for the specified locale, likegetName(String)
, but without keywords.- Parameters:
localeID
- the locale ID as a string- Returns:
- the base name as a String.
-
getName
public java.lang.String getName()
Returns the (normalized) full name for this locale.- Returns:
- String the full name of the localeID
-
getName
public static java.lang.String getName(java.lang.String localeID)
Returns the (normalized) full name for the specified locale.- Parameters:
localeID
- the localeID as a string- Returns:
- String the full name of the localeID
-
toString
public java.lang.String toString()
Returns a string representation of this object.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation of the object.
-
getKeywords
public java.util.Iterator<java.lang.String> getKeywords()
Returns an iterator over keywords for this locale. If there are no keywords, returns null.- Returns:
- iterator over keywords, or null if there are no keywords.
-
getKeywords
public static java.util.Iterator<java.lang.String> getKeywords(java.lang.String localeID)
Returns an iterator over keywords for the specified locale. If there are no keywords, returns null.- Returns:
- an iterator over the keywords in the specified locale, or null if there are no keywords.
-
getKeywordValue
public java.lang.String getKeywordValue(java.lang.String keywordName)
Returns the value for a keyword in this locale. If the keyword is not defined, returns null.- Parameters:
keywordName
- name of the keyword whose value is desired. Case insensitive.- Returns:
- the value of the keyword, or null.
-
getKeywordValue
public static java.lang.String getKeywordValue(java.lang.String localeID, java.lang.String keywordName)
Returns the value for a keyword in the specified locale. If the keyword is not defined, returns null. The locale name does not need to be normalized.- Parameters:
keywordName
- name of the keyword whose value is desired. Case insensitive.- Returns:
- String the value of the keyword as a string
-
canonicalize
public static java.lang.String canonicalize(java.lang.String localeID)
Returns the canonical name according to CLDR for the specified locale ID. This is used to convert POSIX and other legacy IDs to standard ICU form.- Parameters:
localeID
- the locale id- Returns:
- the canonicalized id
-
setKeywordValue
public ULocale setKeywordValue(java.lang.String keyword, java.lang.String value)
Given a keyword and a value, return a new locale with an updated keyword and value. If the keyword is null, this removes all keywords from the locale id. Otherwise, if the value is null, this removes the value for this keyword from the locale id. Otherwise, this adds/replaces the value for this keyword in the locale id. The keyword and value must not be empty.Related:
getBaseName()
returns the locale ID string with all keywords removed.- Parameters:
keyword
- the keyword to add/remove, or null to remove all keywords.value
- the value to add/set, or null to remove this particular keyword.- Returns:
- the updated locale
-
setKeywordValue
public static java.lang.String setKeywordValue(java.lang.String localeID, java.lang.String keyword, java.lang.String value)
Given a locale id, a keyword, and a value, return a new locale id with an updated keyword and value. If the keyword is null, this removes all keywords from the locale id. Otherwise, if the value is null, this removes the value for this keyword from the locale id. Otherwise, this adds/replaces the value for this keyword in the locale id. The keyword and value must not be empty.Related:
getBaseName(String)
returns the locale ID string with all keywords removed.- Parameters:
localeID
- the locale id to modifykeyword
- the keyword to add/remove, or null to remove all keywords.value
- the value to add/set, or null to remove this particular keyword.- Returns:
- the updated locale id
-
getISO3Language
public java.lang.String getISO3Language()
Returns a three-letter abbreviation for this locale's language. If the locale doesn't specify a language, returns the empty string. Otherwise, returns a lowercase ISO 639-2/T language code. The ISO 639-2 language codes can be found on-line atftp://dkuug.dk/i18n/iso-639-2.txt
- Throws:
java.util.MissingResourceException
- Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.
-
getISO3Language
public static java.lang.String getISO3Language(java.lang.String localeID)
Returns a three-letter abbreviation for this locale's language. If the locale doesn't specify a language, returns the empty string. Otherwise, returns a lowercase ISO 639-2/T language code. The ISO 639-2 language codes can be found on-line atftp://dkuug.dk/i18n/iso-639-2.txt
- Throws:
java.util.MissingResourceException
- Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.
-
getISO3Country
public java.lang.String getISO3Country()
Returns a three-letter abbreviation for this locale's country/region. If the locale doesn't specify a country, returns the empty string. Otherwise, returns an uppercase ISO 3166 3-letter country code.- Throws:
java.util.MissingResourceException
- Throws MissingResourceException if the three-letter country abbreviation is not available for this locale.
-
getISO3Country
public static java.lang.String getISO3Country(java.lang.String localeID)
Returns a three-letter abbreviation for this locale's country/region. If the locale doesn't specify a country, returns the empty string. Otherwise, returns an uppercase ISO 3166 3-letter country code.- Throws:
java.util.MissingResourceException
- Throws MissingResourceException if the three-letter country abbreviation is not available for this locale.
-
isRightToLeft
public boolean isRightToLeft()
Returns whether this locale's script is written right-to-left. If there is no script subtag, then the likely script is used, seeaddLikelySubtags(ULocale)
. 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
-
getDisplayLanguage
public java.lang.String getDisplayLanguage()
Returns this locale's language localized for display in the defaultDISPLAY
locale.- Returns:
- the localized language name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayLanguage
public java.lang.String getDisplayLanguage(ULocale displayLocale)
Returns this locale's language localized for display in the provided locale.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayLanguage
public static java.lang.String getDisplayLanguage(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's language localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose language will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayLanguage
public static java.lang.String getDisplayLanguage(java.lang.String localeID, ULocale displayLocale)
Returns a locale's language localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose language will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayLanguageWithDialect
public java.lang.String getDisplayLanguageWithDialect()
Returns this locale's language localized for display in the defaultDISPLAY
locale. If a dialect name is present in the data, then it is returned.- Returns:
- the localized language name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayLanguageWithDialect
public java.lang.String getDisplayLanguageWithDialect(ULocale displayLocale)
Returns this locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayLanguageWithDialect
public static java.lang.String getDisplayLanguageWithDialect(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose language will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayLanguageWithDialect
public static java.lang.String getDisplayLanguageWithDialect(java.lang.String localeID, ULocale displayLocale)
Returns a locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose language will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized language name.
-
getDisplayScript
public java.lang.String getDisplayScript()
Returns this locale's script localized for display in the defaultDISPLAY
locale.- Returns:
- the localized script name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayScriptInContext
@Deprecated public java.lang.String getDisplayScriptInContext()
Deprecated.This API is ICU internal only.Returns this locale's script localized for display in the defaultDISPLAY
locale.- Returns:
- the localized script name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayScript
public java.lang.String getDisplayScript(ULocale displayLocale)
Returns this locale's script localized for display in the provided locale.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayScriptInContext
@Deprecated public java.lang.String getDisplayScriptInContext(ULocale displayLocale)
Deprecated.This API is ICU internal only.Returns this locale's script localized for display in the provided locale.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayScript
public static java.lang.String getDisplayScript(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's script localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose script will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayScriptInContext
@Deprecated public static java.lang.String getDisplayScriptInContext(java.lang.String localeID, java.lang.String displayLocaleID)
Deprecated.This API is ICU internal only.Returns a locale's script localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose script will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayScript
public static java.lang.String getDisplayScript(java.lang.String localeID, ULocale displayLocale)
Returns a locale's script localized for display in the provided locale.- Parameters:
localeID
- the id of the locale whose script will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayScriptInContext
@Deprecated public static java.lang.String getDisplayScriptInContext(java.lang.String localeID, ULocale displayLocale)
Deprecated.This API is ICU internal only.Returns a locale's script localized for display in the provided locale.- Parameters:
localeID
- the id of the locale whose script will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized script name.
-
getDisplayCountry
public java.lang.String getDisplayCountry()
Returns this locale's country localized for display in the defaultDISPLAY
locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, useLocaleDisplayNames
instead.- Returns:
- the localized country name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayCountry
public java.lang.String getDisplayCountry(ULocale displayLocale)
Returns this locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, useLocaleDisplayNames
instead.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized country name.
-
getDisplayCountry
public static java.lang.String getDisplayCountry(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, useLocaleDisplayNames
instead. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose country will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized country name.
-
getDisplayCountry
public static java.lang.String getDisplayCountry(java.lang.String localeID, ULocale displayLocale)
Returns a locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, useLocaleDisplayNames
instead. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose country will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized country name.
-
getDisplayVariant
public java.lang.String getDisplayVariant()
Returns this locale's variant localized for display in the defaultDISPLAY
locale.- Returns:
- the localized variant name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayVariant
public java.lang.String getDisplayVariant(ULocale displayLocale)
Returns this locale's variant localized for display in the provided locale.- Parameters:
displayLocale
- the locale in which to display the name.- Returns:
- the localized variant name.
-
getDisplayVariant
public static java.lang.String getDisplayVariant(java.lang.String localeID, java.lang.String displayLocaleID)
Returns a locale's variant localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose variant will be displayeddisplayLocaleID
- the id of the locale in which to display the name.- Returns:
- the localized variant name.
-
getDisplayVariant
public static java.lang.String getDisplayVariant(java.lang.String localeID, ULocale displayLocale)
Returns a locale's variant localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose variant will be displayed.displayLocale
- the locale in which to display the name.- Returns:
- the localized variant name.
-
getDisplayKeyword
public static java.lang.String getDisplayKeyword(java.lang.String keyword)
Returns a keyword localized for display in the defaultDISPLAY
locale.- Parameters:
keyword
- the keyword to be displayed.- Returns:
- the localized keyword name.
- See Also:
getKeywords()
,ULocale.Category.DISPLAY
-
getDisplayKeyword
public static java.lang.String getDisplayKeyword(java.lang.String keyword, java.lang.String displayLocaleID)
Returns a keyword localized for display in the specified locale.- Parameters:
keyword
- the keyword to be displayed.displayLocaleID
- the id of the locale in which to display the keyword.- Returns:
- the localized keyword name.
- See Also:
getKeywords(String)
-
getDisplayKeyword
public static java.lang.String getDisplayKeyword(java.lang.String keyword, ULocale displayLocale)
Returns a keyword localized for display in the specified locale.- Parameters:
keyword
- the keyword to be displayed.displayLocale
- the locale in which to display the keyword.- Returns:
- the localized keyword name.
- See Also:
getKeywords(String)
-
getDisplayKeywordValue
public java.lang.String getDisplayKeywordValue(java.lang.String keyword)
Returns a keyword value localized for display in the defaultDISPLAY
locale.- Parameters:
keyword
- the keyword whose value is to be displayed.- Returns:
- the localized value name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayKeywordValue
public java.lang.String getDisplayKeywordValue(java.lang.String keyword, ULocale displayLocale)
Returns a keyword value localized for display in the specified locale.- Parameters:
keyword
- the keyword whose value is to be displayed.displayLocale
- the locale in which to display the value.- Returns:
- the localized value name.
-
getDisplayKeywordValue
public static java.lang.String getDisplayKeywordValue(java.lang.String localeID, java.lang.String keyword, java.lang.String displayLocaleID)
Returns a keyword value localized for display in the specified locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose keyword value is to be displayed.keyword
- the keyword whose value is to be displayed.displayLocaleID
- the id of the locale in which to display the value.- Returns:
- the localized value name.
-
getDisplayKeywordValue
public static java.lang.String getDisplayKeywordValue(java.lang.String localeID, java.lang.String keyword, ULocale displayLocale)
Returns a keyword value localized for display in the specified locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the id of the locale whose keyword value is to be displayed.keyword
- the keyword whose value is to be displayed.displayLocale
- the id of the locale in which to display the value.- Returns:
- the localized value name.
-
getDisplayName
public java.lang.String getDisplayName()
Returns this locale name localized for display in the defaultDISPLAY
locale.- Returns:
- the localized locale name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayName
public java.lang.String getDisplayName(ULocale displayLocale)
Returns this locale name localized for display in the provided locale.- Parameters:
displayLocale
- the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getDisplayName
public static java.lang.String getDisplayName(java.lang.String localeID, java.lang.String displayLocaleID)
Returns the locale ID localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the locale whose name is to be displayed.displayLocaleID
- the id of the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getDisplayName
public static java.lang.String getDisplayName(java.lang.String localeID, ULocale displayLocale)
Returns the locale ID localized for display in the provided locale. This is a cover for the ICU4C API.- Parameters:
localeID
- the locale whose name is to be displayed.displayLocale
- the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getDisplayNameWithDialect
public java.lang.String getDisplayNameWithDialect()
Returns this locale name localized for display in the defaultDISPLAY
locale. If a dialect name is present in the locale data, then it is returned.- Returns:
- the localized locale name.
- See Also:
ULocale.Category.DISPLAY
-
getDisplayNameWithDialect
public java.lang.String getDisplayNameWithDialect(ULocale displayLocale)
Returns this locale name localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned.- Parameters:
displayLocale
- the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getDisplayNameWithDialect
public static java.lang.String getDisplayNameWithDialect(java.lang.String localeID, java.lang.String displayLocaleID)
Returns the locale ID localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned. This is a cover for the ICU4C API.- Parameters:
localeID
- the locale whose name is to be displayed.displayLocaleID
- the id of the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getDisplayNameWithDialect
public static java.lang.String getDisplayNameWithDialect(java.lang.String localeID, ULocale displayLocale)
Returns the locale ID localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned. This is a cover for the ICU4C API.- Parameters:
localeID
- the locale whose name is to be displayed.displayLocale
- the locale in which to display the locale name.- Returns:
- the localized locale name.
-
getCharacterOrientation
public java.lang.String getCharacterOrientation()
Returns this locale's layout orientation for characters. The possible values are "left-to-right", "right-to-left", "top-to-bottom" or "bottom-to-top".- Returns:
- The locale's layout orientation for characters.
-
getLineOrientation
public java.lang.String getLineOrientation()
Returns this locale's layout orientation for lines. The possible values are "left-to-right", "right-to-left", "top-to-bottom" or "bottom-to-top".- Returns:
- The locale's layout orientation for lines.
-
acceptLanguage
public static ULocale acceptLanguage(java.lang.String acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)
Based on a HTTP formatted list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case.This is a thin wrapper over
LocalePriorityList
+LocaleMatcher
.- Parameters:
acceptLanguageList
- list in HTTP "Accept-Language:" format of acceptable localesavailableLocales
- list of available locales. One of these will be returned.fallback
- if non-null, a 1-element array containing a boolean to be set with the fallback status- Returns:
- one of the locales from the availableLocales list, or null if none match
- See Also:
LocaleMatcher
,LocalePriorityList
-
acceptLanguage
public static ULocale acceptLanguage(ULocale[] acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)
Based on a list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case.This is a thin wrapper over
LocaleMatcher
.- Parameters:
acceptLanguageList
- list of acceptable localesavailableLocales
- list of available locales. One of these will be returned.fallback
- if non-null, a 1-element array containing a boolean to be set with the fallback status- Returns:
- one of the locales from the availableLocales list, or null if none match
- See Also:
LocaleMatcher
-
acceptLanguage
public static ULocale acceptLanguage(java.lang.String acceptLanguageList, boolean[] fallback)
Based on a HTTP formatted list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case. This function will choose a locale from the ULocale.getAvailableLocales() list as available.This is a thin wrapper over
LocalePriorityList
+LocaleMatcher
.- Parameters:
acceptLanguageList
- list in HTTP "Accept-Language:" format of acceptable localesfallback
- if non-null, a 1-element array containing a boolean to be set with the fallback status- Returns:
- one of the locales from the ULocale.getAvailableLocales() list, or null if none match
- See Also:
LocaleMatcher
,LocalePriorityList
-
acceptLanguage
public static ULocale acceptLanguage(ULocale[] acceptLanguageList, boolean[] fallback)
Based on an ordered array of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case. This function will choose a locale from the ULocale.getAvailableLocales() list as available.This is a thin wrapper over
LocaleMatcher
.- Parameters:
acceptLanguageList
- ordered array of acceptable locales (preferred are listed first)fallback
- if non-null, a 1-element array containing a boolean to be set with the fallback status- Returns:
- one of the locales from the ULocale.getAvailableLocales() list, or null if none match
- See Also:
LocaleMatcher
-
addLikelySubtags
public static ULocale addLikelySubtags(ULocale loc)
Adds the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags If the provided ULocale instance is already in the maximal form, or there is no data available available for maximization, it will be returned. For example, "und-Zzzz" cannot be maximized, since there is no reasonable maximization. Otherwise, a new ULocale instance with the maximal form is returned. Examples: "en" maximizes to "en_Latn_US" "de" maximizes to "de_Latn_US" "sr" maximizes to "sr_Cyrl_RS" "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.) "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)- Parameters:
loc
- The ULocale to maximize- Returns:
- The maximized ULocale instance.
-
minimizeSubtags
public static ULocale minimizeSubtags(ULocale loc)
Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:http://www.unicode.org/reports/tr35/#Likely_Subtags
If the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned. 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:
loc
- The ULocale to minimize- Returns:
- The minimized ULocale instance.
-
minimizeSubtags
@Deprecated public static ULocale minimizeSubtags(ULocale loc, ULocale.Minimize fieldToFavor)
Deprecated.This API is ICU internal only.Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report:http://www.unicode.org/reports/tr35/#Likely_Subtags
If the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned. 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" if fieldToFavor ==
The fieldToFavor only has an effect if either the region or the script could be suppressed, but not both.ULocale.Minimize.FAVOR_REGION
"zh_Hant_TW" minimizes to "zh_Hant" if fieldToFavor ==ULocale.Minimize.FAVOR_SCRIPT
- Parameters:
loc
- The ULocale to minimizefieldToFavor
- Indicate which should be preferred, when either the region or the script could be suppressed, but not both.- Returns:
- The minimized ULocale instance.
-
getExtension
public java.lang.String getExtension(char key)
Returns the extension (or private use) value associated with the specified key, or null if there is no extension associated with the key. To be well-formed, the key must be one of[0-9A-Za-z]
. Keys are case-insensitive, so for example 'z' and 'Z' represent the same extension.- Parameters:
key
- the extension key- Returns:
- The extension, or null if this locale defines no extension for the specified key.
- Throws:
java.lang.IllegalArgumentException
- if key is not well-formed- See Also:
PRIVATE_USE_EXTENSION
,UNICODE_LOCALE_EXTENSION
-
getExtensionKeys
public java.util.Set<java.lang.Character> getExtensionKeys()
Returns the set of extension keys associated with this locale, or the empty set if it has no extensions. The returned set is unmodifiable. The keys will all be lower-case.- Returns:
- the set of extension keys, or the empty set if this locale has no extensions
-
getUnicodeLocaleAttributes
public java.util.Set<java.lang.String> getUnicodeLocaleAttributes()
Returns the set of unicode locale attributes associated with this locale, or the empty set if it has no attributes. The returned set is unmodifiable.- Returns:
- The set of attributes.
-
getUnicodeLocaleType
public java.lang.String getUnicodeLocaleType(java.lang.String key)
Returns the Unicode locale type associated with the specified Unicode locale key for this locale. Returns the empty string for keys that are defined with no type. Returns null if the key is not defined. Keys are case-insensitive. The key must be two alphanumeric characters ([0-9a-zA-Z]), or an IllegalArgumentException is thrown.- Parameters:
key
- the Unicode locale key- Returns:
- The Unicode locale type associated with the key, or null if the locale does not define the key.
- Throws:
java.lang.IllegalArgumentException
- if the key is not well-formedjava.lang.NullPointerException
- ifkey
is null
-
getUnicodeLocaleKeys
public java.util.Set<java.lang.String> getUnicodeLocaleKeys()
Returns the set of Unicode locale keys defined by this locale, or the empty set if this locale has none. The returned set is immutable. Keys are all lower case.- Returns:
- The set of Unicode locale keys, or the empty set if this locale has no Unicode locale keywords.
-
toLanguageTag
public java.lang.String toLanguageTag()
Returns a well-formed IETF BCP 47 language tag representing this locale.If this
ULocale
has a language, script, country, or variant that does not satisfy the IETF BCP 47 language tag syntax requirements, this method handles these fields as described below:Language: If language is empty, or not well-formed (for example "a" or "e2"), it will be emitted as "und" (Undetermined).
Script: If script is not well-formed (for example "12" or "Latin"), it will be omitted.
Country: If country is not well-formed (for example "12" or "USA"), it will be omitted.
Variant: If variant is well-formed, each sub-segment (delimited by '-' or '_') is emitted as a subtag. Otherwise:
- if all sub-segments match
[0-9a-zA-Z]{1,8}
(for example "WIN" or "Oracle_JDK_Standard_Edition"), the first ill-formed sub-segment and all following will be appended to the private use subtag. The first appended subtag will be "lvariant", followed by the sub-segments in order, separated by hyphen. For example, "x-lvariant-WIN", "Oracle-x-lvariant-JDK-Standard-Edition". - if any sub-segment does not match
[0-9a-zA-Z]{1,8}
, the variant will be truncated and the problematic sub-segment and all following sub-segments will be omitted. If the remainder is non-empty, it will be emitted as a private use subtag as above (even if the remainder turns out to be well-formed). For example, "Solaris_isjustthecoolestthing" is emitted as "x-lvariant-Solaris", not as "solaris".
Note: Although the language tag created by this method is well-formed (satisfies the syntax requirements defined by the IETF BCP 47 specification), it is not necessarily a valid BCP 47 language tag. For example,
new Locale("xx", "YY").toLanguageTag();
will return "xx-YY", but the language subtag "xx" and the region subtag "YY" are invalid because they are not registered in the IANA Language Subtag Registry.- Returns:
- a BCP47 language tag representing the locale
- See Also:
forLanguageTag(String)
- if all sub-segments match
-
forLanguageTag
public static ULocale forLanguageTag(java.lang.String languageTag)
Returns a locale for the specified IETF BCP 47 language tag string.If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored. Compare to
ULocale.Builder.setLanguageTag(java.lang.String)
which throws an exception in this case.The following conversions are performed:
- The language code "und" is mapped to language "".
- The portion of a private use subtag prefixed by "lvariant",
if any, is removed and appended to the variant field in the
result locale (without case normalization). If it is then
empty, the private use subtag is discarded:
ULocale loc; loc = ULocale.forLanguageTag("en-US-x-lvariant-icu4j); loc.getVariant(); // returns "ICU4J" loc.getExtension('x'); // returns null loc = Locale.forLanguageTag("de-icu4j-x-URP-lvariant-Abc-Def"); loc.getVariant(); // returns "ICU4J_ABC_DEF" loc.getExtension('x'); // returns "urp"
- When the languageTag argument contains an extlang subtag,
the first such subtag is used as the language, and the primary
language subtag and other extlang subtags are ignored:
ULocale.forLanguageTag("ar-aao").getLanguage(); // returns "aao" ULocale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
- Case is normalized. Language is normalized to lower case, script to title case, country to upper case, variant to upper case, and extensions to lower case.
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.
Stand-alone private use tags are represented as empty language and extension '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.
Note: there is no guarantee that
toLanguageTag
andforLanguageTag
will round-trip.- Parameters:
languageTag
- the language tag- Returns:
- The locale that best represents the language tag.
- Throws:
java.lang.NullPointerException
- iflanguageTag
isnull
- See Also:
toLanguageTag()
,ULocale.Builder.setLanguageTag(String)
-
toUnicodeLocaleKey
public static java.lang.String toUnicodeLocaleKey(java.lang.String keyword)
Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key. For example, BCP 47 Unicode locale extension key "co" is returned for the input keyword "collation".When the specified keyword is unknown, but satisfies the BCP syntax, then the lower-case version of the input keyword will be returned. For example,
toUnicodeLocaleKey("ZZ")
returns "zz".- Parameters:
keyword
- the input locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").- Returns:
- the well-formed BCP 47 Unicode locale extension key, or null if the specified locale keyword cannot be mapped to a well-formed BCP 47 Unicode locale extension key.
- See Also:
toLegacyKey(String)
-
toUnicodeLocaleType
public static java.lang.String toUnicodeLocaleType(java.lang.String keyword, java.lang.String value)
Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category). For example, BCP 47 Unicode locale extension type "phonebk" is returned for the input keyword value "phonebook", with the keyword "collation" (or "co").When the specified keyword is not recognized, but the specified value satisfies the syntax of the BCP 47 Unicode locale extension type, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, the lower-case version of the input value will be returned. For example,
toUnicodeLocaleType("Foo", "Bar")
returns "bar",toUnicodeLocaleType("variableTop", "00A4")
returns "00a4".- Parameters:
keyword
- the locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").value
- the locale keyword value (either legacy type such as "phonebook" or BCP 47 Unicode locale extension type such as "phonebk").- Returns:
- the well-formed BCP47 Unicode locale extension type, or null if the locale keyword value cannot be mapped to a well-formed BCP 47 Unicode locale extension type.
- See Also:
toLegacyType(String, String)
-
toLegacyKey
public static java.lang.String toLegacyKey(java.lang.String keyword)
Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key. For example, legacy key "collation" is returned for the input BCP 47 Unicode locale extension key "co".- Parameters:
keyword
- the input locale keyword (either BCP 47 Unicode locale extension key or legacy key).- Returns:
- the well-formed legacy key, or null if the specified keyword cannot be mapped to a well-formed legacy key.
- See Also:
toUnicodeLocaleKey(String)
-
toLegacyType
public static java.lang.String toLegacyType(java.lang.String keyword, java.lang.String value)
Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type. For example, the legacy type "phonebook" is returned for the input BCP 47 Unicode locale extension type "phonebk" with the keyword "collation" (or "co").When the specified keyword is not recognized, but the specified value satisfies the syntax of legacy key, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, the lower-case version of the input value will be returned. For example,
toLegacyType("Foo", "Bar")
returns "bar",toLegacyType("vt", "00A4")
returns "00a4".- Parameters:
keyword
- the locale keyword (either legacy keyword such as "collation" or BCP 47 Unicode locale extension key such as "co").value
- the locale keyword value (either BCP 47 Unicode locale extension type such as "phonebk" or legacy keyword value such as "phonebook").- Returns:
- the well-formed legacy type, or null if the specified keyword value cannot be mapped to a well-formed legacy type.
- See Also:
toUnicodeLocaleType(String, String)
-
-