Package org.apache.sis.util

# Class Locales

Object
Static
Locales

public final class Locales extends Static
Static methods working on `Locale` instances. While this class is documented as providing static methods, a few methods are actually non-static. Those methods need to be invoked on the `ALL` or `SIS` instance in order to specify the scope. Examples:

>     Locales[] lc1 = Locales.ALL.getAvailableLanguages();  // All languages installed on the JavaVM.
>     Locales[] lc2 = Locales.SIS.getAvailableLanguages();  // Only the languages known to Apache SIS.

Since:
  0.3

Defined in the `sis-utility` module

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Locales`
  `ALL`
  All locales available on the JavaVM.
  `static final Locales`
  `SIS`
  Only locales available in the Apache SIS library.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Locale[]`
  `getAvailableLanguages()`
  Returns the languages known to the JavaVM (`ALL`) or to the Apache SIS library (`SIS`).
  `Locale[]`
  `getAvailableLocales()`
  Returns the locales known to the JavaVM (`ALL`) or to the Apache SIS library (`SIS`).
  `static Locale`
  `parse(String code)`
  Parses the given language code, optionally followed by country code and variant.
  `static Locale`
  `parse(String code, int fromIndex)`
  Parses the given language code and optional complements (country, variant), starting at the given index.
  `static Locale`
  `unique(Locale locale)`
  Returns a unique instance of the given locale, if one is available.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### ALL

    public static final Locales ALL
    All locales available on the JavaVM.

  - ### SIS

    public static final Locales SIS
    Only locales available in the Apache SIS library.

- ## Method Details

  - ### getAvailableLanguages

    public Locale[] getAvailableLanguages()
    Returns the languages known to the JavaVM (`ALL`) or to the Apache SIS library (`SIS`). In the later case, this method returns only the languages for which localized resources are provided in the `org​.apache​.sis​.util​.resources` package.
    Returns:
      the list of supported languages.

  - ### getAvailableLocales

    public Locale[] getAvailableLocales()
    Returns the locales known to the JavaVM (`ALL`) or to the Apache SIS library (`SIS`). In the later case, this method returns only the locales for which localized resources are provided in the `org​.apache​.sis​.util​.resources` package.
    Returns:
      the list of supported locales.

  - ### parse

    public static Locale parse(String code) throws IllformedLocaleException
    Parses the given language code, optionally followed by country code and variant. The given string can be either the 2 letters or the 3 letters ISO 639 code. It can optionally be followed by the `'_'` character and the country code (again either as 2 or 3 letters), optionally followed by `'_'` and the variant.

    This method can be used when the caller wants the same `Locale` constants no matter if the language and country codes use 2 or 3 letters. This method tries to convert 3-letters codes to 2-letters code on a best effort basis.

    Parameters:
      `code` - the language code, optionally followed by country code and variant.
    Returns:
      the language for the given code (never `null`).
    Throws:
      `IllformedLocaleException` - if the given code is not valid.
    See Also:
      - `Locale​.forLanguageTag(String)`

  - ### parse

    public static Locale parse(String code, int fromIndex) throws IllformedLocaleException
    Parses the given language code and optional complements (country, variant), starting at the given index. All characters before `fromIndex` are ignored. Characters from `fromIndex` to the end of the string are parsed as documented in the `parse(String)` method. In particular, this method tries to convert 3-letters codes to 2-letters code on a best effort basis.
    Example: This method is useful when language codes are appended to a base property or resource name. For example a dictionary may define the `"remarks"` property by values associated to the `"remarks_en"` and `"remarks_fr"` keys, for English and French locales respectively.
    Parameters:
      `code` - the language code, which may be followed by country code.
      `fromIndex` - index of the first character to parse.
    Returns:
      the language for the given code (never `null`).
    Throws:
      `IllformedLocaleException` - if the given code is not valid.
    See Also:
      - `Locale​.forLanguageTag(String)`
      - `Types​.toInternationalString(Map, String)`

  - ### unique

    public static Locale unique(Locale locale)
    Returns a unique instance of the given locale, if one is available. Otherwise returns the `locale` unchanged.
    Parameters:
      `locale` - the locale to canonicalize.
    Returns:
      a unique instance of the given locale, or `locale` if the given locale is not cached.