Package org.apache.commons.lang3

Class LocaleUtils

  • public class LocaleUtils
extends java.lang.Object

    Operations to assist when working with a Locale.

    This class tries to handle null input gracefully. An exception will not be thrown for a null input. Each method documents its behavior in more detail.

    Since:
    2.2

    • 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.
      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 list of available locales.
      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.
      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, otherwise Locale.getDefault().

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • LocaleUtils

        public LocaleUtils()

        LocaleUtils instances should NOT be constructed in standard programming. Instead, the class should be used as LocaleUtils.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

      • 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 list of available locales.

        Parameters:
        locale - the Locale object to check if it is available
        Returns:
        true if the locale is a known locale

      • 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 list
        defaultLocale - the default locale to use if no other is found
        Returns:
        the unmodifiable list of Locale objects, 0 being locale, not null

      • toLocale

        public static java.util.Locale toLocale​(java.util.Locale locale)
        Returns the given locale if non-null, otherwise Locale.getDefault().
        Parameters:
        locale - a locale or null.
        Returns:
        the given locale if non-null, otherwise Locale.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_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. 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)