Package org.zkoss.util

## Class Locales

- java.lang.Object
- - org.zkoss.util.Locales

-     public class Locales
      extends java.lang.Object

  The locale relevant utilities.
  Author:
    tomyeh

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Locales()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.util.Locale` | `getByFallback​(java.util.Collection<java.util.Locale> values, java.util.Locale locale)` | Returns any occurrence of the specified Locale or any its fallback in the value collection, or null if not found.
    `static java.util.Locale` | `getCurrent()` | Returns the current locale; never null.
    `static java.util.Locale` | `getLocale​(java.lang.String localeString)` | Converts a string that consists of language, country and variant to a locale.
    `static java.util.Locale` | `getLocale​(java.lang.String localeString, char separator)` | Converts a string that consists of language, country and variant to a locale.
    `static java.util.Locale` | `getLocale​(java.util.Locale locale)` | Converts a Locale to one of them being used before.
    `static java.util.Locale` | `getThreadLocal()` | Returns the locale defined by `setThreadLocal(java.util.Locale)`.
    `static int` | `indexOfUnderline​(java.lang.String s)` | Returns the index of '_' preceding the country part.
    `static int` | `indexOfUnderline​(java.lang.String s, int j)` | Returns the index of '_' preceding the country part, starting from j.
    `static java.util.Locale` | `setThreadLocal​(java.util.Locale locale)` | Sets the locale for the current thread only.
    `static boolean` | `testCurrent​(java.lang.String lang, java.lang.String country)` | Returns whether the current locale (`getCurrent()`) belongs to the specified language and/or country.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Locales

          public Locales()

  - ### Method Detail

    - #### getCurrent

          public static final java.util.Locale getCurrent()

      Returns the current locale; never null. This is the locale that every other objects shall use, unless they have special consideration.

      Default: If `setThreadLocal(java.util.Locale)` was called with non-null, the value is returned. Otherwise, Locale.getDefault() is returned,

    - #### testCurrent

          public static final boolean testCurrent​(java.lang.String lang,
                                                  java.lang.String country)

      Returns whether the current locale (`getCurrent()`) belongs to the specified language and/or country.
      Parameters:
        `lang` - the language code, e.g., en and zh. Ignored if null.
        `country` - the country code, e.g., US. Ignored if null. If empty, it means no country code at all.

    - #### setThreadLocal

          public static final java.util.Locale setThreadLocal​(java.util.Locale locale)

      Sets the locale for the current thread only.

      Each thread could have an independent locale, called the thread locale.

      When Invoking this method under a thread that serves requests, remember to clean up the setting upon completing each request.

          Locale old = Locales.setThreadLocal(newValue);
          try {
            ...
          } finally {
            Locales.setThreadLocal(old);
          }

      Parameters:
        `locale` - the thread locale; null to denote no thread locale
      Returns:
        the previous thread locale

    - #### getThreadLocal

          public static final java.util.Locale getThreadLocal()

      Returns the locale defined by `setThreadLocal(java.util.Locale)`.
      Since:
        3.0.0
      See Also:
        `getCurrent()`

    - #### getLocale

          public static final java.util.Locale getLocale​(java.lang.String localeString,
                                                         char separator)

      Converts a string that consists of language, country and variant to a locale.

      The separator between language, country and variant is customizable, and whitespaces are ignored, e.g., "zh_TW" and "zh, TW".

      Thus, locale.equals(Locales.getLocale(locale.toString(), '_')).

      Parameters:
        `localeString` - the locale in string; null is OK
        `separator` - the separator; ((char)0) means to decide automatically (either ',', '-' or '_')
      Returns:
        the locale or null if locale is null or empty

    - #### getLocale

          public static final java.util.Locale getLocale​(java.lang.String localeString)

      Converts a string that consists of language, country and variant to a locale.

      A shortcut: getLocale(localeString, (char)0).

    - #### getLocale

          public static final java.util.Locale getLocale​(java.util.Locale locale)

      Converts a Locale to one of them being used before. To save memory (since locale is used frequently), it is suggested to pass thru this method after creating a new instance of Locale.
      Example, getLocale(new Locale(...)).

      This method first look for any locale

    - #### getByFallback

          public static java.util.Locale getByFallback​(java.util.Collection<java.util.Locale> values,
                                                       java.util.Locale locale)

      Returns any occurrence of the specified Locale or any its fallback in the value collection, or null if not found. By fallback, we mean will try without variant and country. Example, if locale is zh_TW, it will try zh_TW and then zh.

    - #### indexOfUnderline

          public static int indexOfUnderline​(java.lang.String s,
                                             int j)

      Returns the index of '_' preceding the country part, starting from j. It is similar to s.indexOf('_', j), except it detects country part (which must be only two letter in lower cases.

    - #### indexOfUnderline

          public static int indexOfUnderline​(java.lang.String s)

      Returns the index of '_' preceding the country part. It is similar to s.indexOf('_'), except it detects country part (which must be only two letter in lower cases.