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 Locales` | `ALL` | All locales available on the JavaVM.
    `static Locales` | `SIS` | Only locales available in the Apache SIS library.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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.