Class LocaleUtils
- java.lang.Object
-
- org.apache.commons.lang3.LocaleUtils
-
public class LocaleUtils extends java.lang.Object
Operations to assist when working with aLocale
.This class tries to handle
null
input gracefully. An exception will not be thrown for anull
input. Each method documents its behavior in more detail.- Since:
- 2.2
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
LocaleUtils.SyncAvoid
-
Field Summary
Fields Modifier and Type Field Description private static java.util.concurrent.ConcurrentMap<java.lang.String,java.util.List<java.util.Locale>>
cCountriesByLanguage
Concurrent map of country locales by language.private static java.util.concurrent.ConcurrentMap<java.lang.String,java.util.List<java.util.Locale>>
cLanguagesByCountry
Concurrent map of language locales by country.private static char
DASH
private static char
UNDERSCORE
private static java.lang.String
UNDETERMINED
-
Constructor Summary
Constructors Constructor Description LocaleUtils()
LocaleUtils
instances should NOT be constructed in standard programming.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.util.List<java.util.Locale>
availableLocaleList()
Obtains an unmodifiable list of installed locales.private static java.util.List<java.util.Locale>
availableLocaleList(java.util.function.Predicate<java.util.Locale> predicate)
static java.util.Set<java.util.Locale>
availableLocaleSet()
Obtains an unmodifiable set of installed locales.static java.util.List<java.util.Locale>
countriesByLanguage(java.lang.String languageCode)
Obtains the list of countries supported for a given language.static boolean
isAvailableLocale(java.util.Locale locale)
Checks if the locale specified is in the set of available locales.private static boolean
isISO3166CountryCode(java.lang.String str)
Checks whether the given String is a ISO 3166 alpha-2 country code.private static boolean
isISO639LanguageCode(java.lang.String str)
Checks whether the given String is a ISO 639 compliant language code.static boolean
isLanguageUndetermined(java.util.Locale locale)
Tests whether a Locale's language is undetermined.private static boolean
isNumericAreaCode(java.lang.String str)
Checks whether the given String is a UN M.49 numeric area code.static java.util.List<java.util.Locale>
languagesByCountry(java.lang.String countryCode)
Obtains the list of languages supported for a given country.static java.util.List<java.util.Locale>
localeLookupList(java.util.Locale locale)
Obtains the list of locales to search through when performing a locale search.static java.util.List<java.util.Locale>
localeLookupList(java.util.Locale locale, java.util.Locale defaultLocale)
Obtains the list of locales to search through when performing a locale search.private static java.util.Locale
parseLocale(java.lang.String str)
Tries to parse a locale from the given String.static java.util.Locale
toLocale(java.lang.String str)
Converts a String to a Locale.static java.util.Locale
toLocale(java.util.Locale locale)
Returns the given locale if non-null
, otherwiseLocale.getDefault()
.
-
-
-
Field Detail
-
UNDERSCORE
private static final char UNDERSCORE
- See Also:
- Constant Field Values
-
UNDETERMINED
private static final java.lang.String UNDETERMINED
- See Also:
- Constant Field Values
-
DASH
private static final char DASH
- See Also:
- Constant Field Values
-
cLanguagesByCountry
private static final java.util.concurrent.ConcurrentMap<java.lang.String,java.util.List<java.util.Locale>> cLanguagesByCountry
Concurrent map of language locales by country.
-
cCountriesByLanguage
private static final java.util.concurrent.ConcurrentMap<java.lang.String,java.util.List<java.util.Locale>> cCountriesByLanguage
Concurrent map of country locales by language.
-
-
Constructor Detail
-
LocaleUtils
public LocaleUtils()
LocaleUtils
instances should NOT be constructed in standard programming. Instead, the class should be used asLocaleUtils.toLocale("en_GB");
.This constructor is public to permit tools that require a JavaBean instance to operate.
-
-
Method Detail
-
availableLocaleList
public static java.util.List<java.util.Locale> availableLocaleList()
Obtains an unmodifiable list of installed locales.This method is a wrapper around
Locale.getAvailableLocales()
. It is more efficient, as the JDK method must create a new array each time it is called.- Returns:
- the unmodifiable list of available locales
-
availableLocaleList
private static java.util.List<java.util.Locale> availableLocaleList(java.util.function.Predicate<java.util.Locale> predicate)
-
availableLocaleSet
public static java.util.Set<java.util.Locale> availableLocaleSet()
Obtains an unmodifiable set of installed locales.This method is a wrapper around
Locale.getAvailableLocales()
. It is more efficient, as the JDK method must create a new array each time it is called.- Returns:
- the unmodifiable set of available locales
-
countriesByLanguage
public static java.util.List<java.util.Locale> countriesByLanguage(java.lang.String languageCode)
Obtains the list of countries supported for a given language.This method takes a language code and searches to find the countries available for that language. Variant locales are removed.
- Parameters:
languageCode
- the 2 letter language code, null returns empty- Returns:
- an unmodifiable List of Locale objects, not null
-
isAvailableLocale
public static boolean isAvailableLocale(java.util.Locale locale)
Checks if the locale specified is in the set of available locales.- Parameters:
locale
- the Locale object to check if it is available- Returns:
- true if the locale is a known locale
-
isISO3166CountryCode
private static boolean isISO3166CountryCode(java.lang.String str)
Checks whether the given String is a ISO 3166 alpha-2 country code.- Parameters:
str
- the String to check- Returns:
- true, is the given String is a ISO 3166 compliant country code.
-
isISO639LanguageCode
private static boolean isISO639LanguageCode(java.lang.String str)
Checks whether the given String is a ISO 639 compliant language code.- Parameters:
str
- the String to check.- Returns:
- true, if the given String is a ISO 639 compliant language code.
-
isLanguageUndetermined
public static boolean isLanguageUndetermined(java.util.Locale locale)
Tests whether a Locale's language is undetermined.A Locale's language tag is undetermined if it's value is
"und"
. If a language is empty, or not well-formed (for example, "a" or"e2"), it will be equal to"und"
.- Parameters:
locale
- the locale to test.- Returns:
- whether a Locale's language is undetermined.
- Since:
- 3.14.0
- See Also:
Locale.toLanguageTag()
-
isNumericAreaCode
private static boolean isNumericAreaCode(java.lang.String str)
Checks whether the given String is a UN M.49 numeric area code.- Parameters:
str
- the String to check- Returns:
- true, is the given String is a UN M.49 numeric area code.
-
languagesByCountry
public static java.util.List<java.util.Locale> languagesByCountry(java.lang.String countryCode)
Obtains the list of languages supported for a given country.This method takes a country code and searches to find the languages available for that country. Variant locales are removed.
- Parameters:
countryCode
- the 2-letter country code, null returns empty- Returns:
- an unmodifiable List of Locale objects, not null
-
localeLookupList
public static java.util.List<java.util.Locale> localeLookupList(java.util.Locale locale)
Obtains the list of locales to search through when performing a locale search.localeLookupList(Locale("fr", "CA", "xxx")) = [Locale("fr", "CA", "xxx"), Locale("fr", "CA"), Locale("fr")]
- Parameters:
locale
- the locale to start from- Returns:
- the unmodifiable list of Locale objects, 0 being locale, not null
-
localeLookupList
public static java.util.List<java.util.Locale> localeLookupList(java.util.Locale locale, java.util.Locale defaultLocale)
Obtains the list of locales to search through when performing a locale search.localeLookupList(Locale("fr", "CA", "xxx"), Locale("en")) = [Locale("fr", "CA", "xxx"), Locale("fr", "CA"), Locale("fr"), Locale("en"]
The result list begins with the most specific locale, then the next more general and so on, finishing with the default locale. The list will never contain the same locale twice.
- Parameters:
locale
- the locale to start from, null returns empty listdefaultLocale
- the default locale to use if no other is found- Returns:
- the unmodifiable list of Locale objects, 0 being locale, not null
-
parseLocale
private static java.util.Locale parseLocale(java.lang.String str)
Tries to parse a locale from the given String.- Parameters:
str
- the String to parse a locale from.- Returns:
- a Locale instance parsed from the given String.
- Throws:
java.lang.IllegalArgumentException
- if the given String can not be parsed.
-
toLocale
public static java.util.Locale toLocale(java.util.Locale locale)
Returns the given locale if non-null
, otherwiseLocale.getDefault()
.- Parameters:
locale
- a locale ornull
.- Returns:
- the given locale if non-
null
, otherwiseLocale.getDefault()
. - Since:
- 3.12.0
-
toLocale
public static java.util.Locale toLocale(java.lang.String str)
Converts a String to a Locale.This method takes the string format of a locale and creates the locale object from it.
LocaleUtils.toLocale("") = new Locale("", "") LocaleUtils.toLocale("en") = new Locale("en", "") LocaleUtils.toLocale("en_GB") = new Locale("en", "GB") LocaleUtils.toLocale("en-GB") = new Locale("en", "GB") LocaleUtils.toLocale("en_001") = new Locale("en", "001") LocaleUtils.toLocale("en_GB_xxx") = new Locale("en", "GB", "xxx") (#)
(#) The behavior of the JDK variant constructor changed between JDK1.3 and JDK1.4. In JDK1.3, the constructor upper cases the variant, in JDK1.4, it doesn't. Thus, the result from getVariant() may vary depending on your JDK.
This method validates the input strictly. The language code must be lowercase. The country code must be uppercase. The separator must be an underscore or a dash. The length must be correct.
- Parameters:
str
- the locale String to convert, null returns null- Returns:
- a Locale, null if null input
- Throws:
java.lang.IllegalArgumentException
- if the string is an invalid format- See Also:
Locale.forLanguageTag(String)
-
-