net.sf.okapi.common

## Class LocaleFilter

- java.lang.Object
- - net.sf.okapi.common.LocaleFilter

-     public class LocaleFilter
      extends java.lang.Object

  Provides ways to work with sets of `LocaleId` objects and regular expressions.

  For example `"e.*-us"` to match: `"en-US"` and `"es-US"` but not `"en-GB"`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `LocaleFilter.FilterType` Type of locale filter.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LocaleFilter()` Public constructor.
    `LocaleFilter(java.lang.String string)` Public constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static LocaleFilter` | `any()` Creates a filter of the Any type.
    `static LocaleFilter` | `anyExcept(LocaleId... localeIds)` Creates a filter filtering out the given locales.
    `static LocaleFilter` | `anyOf(LocaleId... localeIds)` Creates a filter allowing only the given locales.
    `static LocaleFilter` | `build(java.lang.String string)` Builds a filter from a configuration string.
    `LocaleFilter` | `exclude(java.util.List<LocaleId> localeIds)` Disallows the locales from a given list of locales.
    `LocaleFilter` | `exclude(LocaleFilter filter)` Disallows all locales allowed in a given locale filter.
    `LocaleFilter` | `exclude(LocaleId... localeIds)` Disallows the locales from a given array of locales.
    `LocaleFilter` | `exclude(LocaleId localeId)` Disallows a given locale.
    `LocaleFilter` | `exclude(java.util.Set<LocaleId> localeIds)` Disallows the locales from a given set of locales.
    `LocaleFilter` | `excludeLanguage(java.lang.String... languages)` Disallows the locales which language matches any of the languages from a given array.
    `LocaleFilter` | `excludeLanguage(java.lang.String language)` Disallows the locales which language matches a given language.
    `LocaleFilter` | `excludePattern(java.lang.String regex)` Disallows all locales matching a given regular expression.
    `LocaleFilter` | `excludePattern(java.lang.String regex, int flags)` Disallows all locales matching a given regular expression with a given set of regex flags.
    `LocaleFilter` | `excludeRegion(java.lang.String... regions)` Disallows the locales which region matches any of the regions from a given array.
    `LocaleFilter` | `excludeRegion(java.lang.String region)` Disallows the locales which region matches a given region.
    `LocaleFilter` | `excludeUserPart(java.lang.String... userParts)` Disallows the locales which user part matches any of the user parts from a given array.
    `LocaleFilter` | `excludeUserPart(java.lang.String userPart)` Disallows the locales which user part matches a given user part.
    `java.util.Set<LocaleId>` | `filter(LocaleId... localeIds)` Creates a subset of the locales from a given array, which are allowed by this locale filter.
    `LocaleFilter` | `fromString(java.lang.String string)` Configures this locale filter from a given configuration string.
    `java.util.List<LocaleId>` | `getExcludes()` Gets a list of disallowed locales.
    `java.util.List<java.lang.String>` | `getExplicitLocaleIds()` If the filter contains only explicitly listed locales (no regex patterns or masks), then returns the list of locale tags of those locales.
    `static java.lang.String` | `getExplicitLocaleIds(java.lang.String string)` Determines if a given string contains only explicitly listed locales.
    `java.util.List<LocaleId>` | `getIncludes()` Gets a list of allowed locales.
    `java.util.List<java.lang.String>` | `getLanguageExcludes()` Gets a list of disallowed languages.
    `java.util.List<java.lang.String>` | `getLanguageIncludes()` Gets a list of allowed languages.
    `java.util.List<java.util.regex.Pattern>` | `getPatternExcludes()` Gets a list of compiled regular expressions for disallowed locales.
    `java.util.List<java.util.regex.Pattern>` | `getPatternIncludes()` Gets a list of compiled regular expressions for allowed locales.
    `java.util.List<java.lang.String>` | `getRegionExcludes()` Gets a list of disallowed regions.
    `java.util.List<java.lang.String>` | `getRegionIncludes()` Gets a list of allowed regions.
    `protected LocaleFilter.FilterType` | `getType()` Helper method.
    `java.util.List<java.lang.String>` | `getUserPartExcludes()` Gets a list of disallowed user parts.
    `java.util.List<java.lang.String>` | `getUserPartIncludes()` Gets a list of allowed user parts.
    `LocaleFilter` | `include(java.util.List<LocaleId> localeIds)` Allows the locales from a given list of locales.
    `LocaleFilter` | `include(LocaleFilter filter)` Allows all locales allowed in a given locale filter.
    `LocaleFilter` | `include(LocaleId... localeIds)` Allows the locales from a given array of locales.
    `LocaleFilter` | `include(LocaleId localeId)` Allows a given locale.
    `LocaleFilter` | `include(java.util.Set<LocaleId> localeIds)` Allows the locales from a given set of locales.
    `LocaleFilter` | `includeLanguage(java.lang.String... languages)` Allows the locales which language matches any of the languages from a given array.
    `LocaleFilter` | `includeLanguage(java.lang.String language)` Allows the locales which language matches a given language.
    `LocaleFilter` | `includePattern(java.lang.String regex)` Allows all locales matching a given regular expression.
    `LocaleFilter` | `includePattern(java.lang.String regex, int flags)` Allows all locales matching a given regular expression with a given set of regex flags.
    `LocaleFilter` | `includeRegion(java.lang.String... regions)` Allows the locales which region matches any of the regions from a given array.
    `LocaleFilter` | `includeRegion(java.lang.String region)` Allows the locales which region matches a given region.
    `LocaleFilter` | `includeUserPart(java.lang.String... userParts)` Allows the locales which user part matches any of the user parts from a given array.
    `LocaleFilter` | `includeUserPart(java.lang.String userPart)` Allows the locales which user part matches a given user part.
    `boolean` | `isEmpty()` Detects if after construction this locale filter was configured with includeXX(), excludeXX().
    `boolean` | `matches(LocaleId localeId)` Returns true if a given locale is allowed by this locale filter.
    `static LocaleFilter` | `none()` Creates a filter of the None type.
    `LocaleFilter` | `reset()` Resets this locale filter to its original right-after-construction state (all settings made with includeXX(), excludeXX() are neglected).
    `protected void` | `setType(LocaleFilter.FilterType type)` Helper method.
    `java.lang.String` | `toString()` Constructs a configuration string for this locale filter.

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

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

- - ### Constructor Detail

    - #### LocaleFilter

          public LocaleFilter()

      Public constructor. Sets filter type to Any.

    - #### LocaleFilter

          public LocaleFilter(java.lang.String string)

      Public constructor. Constructs filter from a string.
      Parameters:
        `string` - the configuration string of locale filter. See `fromString(java.lang.String)` for details.

  - ### Method Detail

    - #### any

          public static LocaleFilter any()

      Creates a filter of the Any type.
      Returns:
        a newly created locale filter.

    - #### none

          public static LocaleFilter none()

      Creates a filter of the None type.
      Returns:
        a newly created locale filter.

    - #### anyOf

          public static LocaleFilter anyOf(LocaleId... localeIds)

      Creates a filter allowing only the given locales.
      Parameters:
        `localeIds` - an array of allowed LocaleId objects.
      Returns:
        a newly created locale filter.

    - #### anyExcept

          public static LocaleFilter anyExcept(LocaleId... localeIds)

      Creates a filter filtering out the given locales.
      Parameters:
        `localeIds` - an array of the LocaleId objects to disallow.
      Returns:
        a newly created locale filter.

    - #### build

          public static LocaleFilter build(java.lang.String string)

      Builds a filter from a configuration string. See `fromString(java.lang.String)` for details on the string format.
      Parameters:
        `string` - the parameters string.
      Returns:
        a newly created locale filter object.

    - #### include

          public LocaleFilter include(LocaleId localeId)

      Allows a given locale.
      Parameters:
        `localeId` - the given locale.
      Returns:
        this locale filter.

    - #### include

          public LocaleFilter include(LocaleId... localeIds)

      Allows the locales from a given array of locales.
      Parameters:
        `localeIds` - the given array of locales.
      Returns:
        this locale filter.

    - #### include

          public LocaleFilter include(java.util.Set<LocaleId> localeIds)

      Allows the locales from a given set of locales.
      Parameters:
        `localeIds` - the given set of locales.
      Returns:
        this locale filter.

    - #### include

          public LocaleFilter include(java.util.List<LocaleId> localeIds)

      Allows the locales from a given list of locales.
      Parameters:
        `localeIds` - the given list of locales.
      Returns:
        this locale filter.

    - #### include

          public LocaleFilter include(LocaleFilter filter)

      Allows all locales allowed in a given locale filter.
      Parameters:
        `filter` - the given locale filter.
      Returns:
        this locale filter.

    - #### includePattern

          public LocaleFilter includePattern(java.lang.String regex,
                                    int flags)

      Allows all locales matching a given regular expression with a given set of regex flags.
      Parameters:
        `regex` - the given regular expression.
        `flags` - the given set of regex flags.
      Returns:
        this locale filter.

    - #### includePattern

          public LocaleFilter includePattern(java.lang.String regex)

      Allows all locales matching a given regular expression.
      Parameters:
        `regex` - the given regular expression.
      Returns:
        this locale filter.

    - #### includeLanguage

          public LocaleFilter includeLanguage(java.lang.String... languages)

      Allows the locales which language matches any of the languages from a given array.
      Parameters:
        `languages` - the given array of languages.
      Returns:
        this locale filter.

    - #### includeLanguage

          public LocaleFilter includeLanguage(java.lang.String language)

      Allows the locales which language matches a given language.
      Parameters:
        `language` - the given language.
      Returns:
        this locale filter.

    - #### includeRegion

          public LocaleFilter includeRegion(java.lang.String... regions)

      Allows the locales which region matches any of the regions from a given array.
      Parameters:
        `regions` - the given array of regions.
      Returns:
        this locale filter.

    - #### includeRegion

          public LocaleFilter includeRegion(java.lang.String region)

      Allows the locales which region matches a given region.
      Parameters:
        `region` - the given region.
      Returns:
        this locale filter.

    - #### includeUserPart

          public LocaleFilter includeUserPart(java.lang.String... userParts)

      Allows the locales which user part matches any of the user parts from a given array.
      Parameters:
        `userParts` - the given array of user parts.
      Returns:
        this locale filter.

    - #### includeUserPart

          public LocaleFilter includeUserPart(java.lang.String userPart)

      Allows the locales which user part matches a given user part.
      Parameters:
        `userPart` - the given user part.
      Returns:
        this locale filter.

    - #### exclude

          public LocaleFilter exclude(LocaleId localeId)

      Disallows a given locale.
      Parameters:
        `localeId` - the given locale.
      Returns:
        this locale filter.

    - #### exclude

          public LocaleFilter exclude(LocaleId... localeIds)

      Disallows the locales from a given array of locales.
      Parameters:
        `localeIds` - the given array of locales.
      Returns:
        this locale filter.

    - #### exclude

          public LocaleFilter exclude(java.util.Set<LocaleId> localeIds)

      Disallows the locales from a given set of locales.
      Parameters:
        `localeIds` - the given set of locales.
      Returns:
        this locale filter.

    - #### exclude

          public LocaleFilter exclude(java.util.List<LocaleId> localeIds)

      Disallows the locales from a given list of locales.
      Parameters:
        `localeIds` - the given list of locales.
      Returns:
        this locale filter.

    - #### exclude

          public LocaleFilter exclude(LocaleFilter filter)

      Disallows all locales allowed in a given locale filter.
      Parameters:
        `filter` - the given locale filter.
      Returns:
        this locale filter.

    - #### excludePattern

          public LocaleFilter excludePattern(java.lang.String regex,
                                    int flags)

      Disallows all locales matching a given regular expression with a given set of regex flags.
      Parameters:
        `regex` - the given regular expression.
        `flags` - the given set of regex flags.
      Returns:
        this locale filter.

    - #### excludePattern

          public LocaleFilter excludePattern(java.lang.String regex)

      Disallows all locales matching a given regular expression.
      Parameters:
        `regex` - the given regular expression.
      Returns:
        this locale filter.

    - #### excludeLanguage

          public LocaleFilter excludeLanguage(java.lang.String... languages)

      Disallows the locales which language matches any of the languages from a given array.
      Parameters:
        `languages` - the given array of languages.
      Returns:
        this locale filter.

    - #### excludeLanguage

          public LocaleFilter excludeLanguage(java.lang.String language)

      Disallows the locales which language matches a given language.
      Parameters:
        `language` - the given language.
      Returns:
        this locale filter.

    - #### excludeRegion

          public LocaleFilter excludeRegion(java.lang.String... regions)

      Disallows the locales which region matches any of the regions from a given array.
      Parameters:
        `regions` - the given array of regions.
      Returns:
        this locale filter.

    - #### excludeRegion

          public LocaleFilter excludeRegion(java.lang.String region)

      Disallows the locales which region matches a given region.
      Parameters:
        `region` - the given region.
      Returns:
        this locale filter.

    - #### excludeUserPart

          public LocaleFilter excludeUserPart(java.lang.String... userParts)

      Disallows the locales which user part matches any of the user parts from a given array.
      Parameters:
        `userParts` - the given array of user parts.
      Returns:
        this locale filter.

    - #### excludeUserPart

          public LocaleFilter excludeUserPart(java.lang.String userPart)

      Disallows the locales which user part matches a given user part.
      Parameters:
        `userPart` - the given user part.
      Returns:
        this locale filter.

    - #### reset

          public LocaleFilter reset()

      Resets this locale filter to its original right-after-construction state (all settings made with includeXX(), excludeXX() are neglected).
      Returns:
        this locale filter.

    - #### matches

          public boolean matches(LocaleId localeId)

      Returns true if a given locale is allowed by this locale filter.
      Parameters:
        `localeId` - the given locale.
      Returns:
        true if the given locale is allowed, false otherwise.

    - #### filter

          public java.util.Set<LocaleId> filter(LocaleId... localeIds)

      Creates a subset of the locales from a given array, which are allowed by this locale filter.
      Parameters:
        `localeIds` - the given array.
      Returns:
        a set of allowed locales.

    - #### getIncludes

          public java.util.List<LocaleId> getIncludes()

      Gets a list of allowed locales.
      Returns:
        the list of allowed locales.

    - #### getExcludes

          public java.util.List<LocaleId> getExcludes()

      Gets a list of disallowed locales.
      Returns:
        the list of disallowed locales.

    - #### getLanguageIncludes

          public java.util.List<java.lang.String> getLanguageIncludes()

      Gets a list of allowed languages.
      Returns:
        the list of allowed languages.

    - #### getRegionIncludes

          public java.util.List<java.lang.String> getRegionIncludes()

      Gets a list of allowed regions.
      Returns:
        the list of allowed regions.

    - #### getUserPartIncludes

          public java.util.List<java.lang.String> getUserPartIncludes()

      Gets a list of allowed user parts.
      Returns:
        the list of allowed user parts.

    - #### getLanguageExcludes

          public java.util.List<java.lang.String> getLanguageExcludes()

      Gets a list of disallowed languages.
      Returns:
        the list of disallowed languages.

    - #### getRegionExcludes

          public java.util.List<java.lang.String> getRegionExcludes()

      Gets a list of disallowed regions.
      Returns:
        the list of disallowed regions.

    - #### getUserPartExcludes

          public java.util.List<java.lang.String> getUserPartExcludes()

      Gets a list of disallowed user parts.
      Returns:
        the list of disallowed user parts.

    - #### getPatternIncludes

          public java.util.List<java.util.regex.Pattern> getPatternIncludes()

      Gets a list of compiled regular expressions for allowed locales.
      Returns:
        the list of compiled regular expressions.

    - #### getPatternExcludes

          public java.util.List<java.util.regex.Pattern> getPatternExcludes()

      Gets a list of compiled regular expressions for disallowed locales.
      Returns:
        the list of compiled regular expressions.

    - #### getType

          protected LocaleFilter.FilterType getType()

      Helper method. Gets the locale filter type (either None or Any).
      Returns:
        None or Any locale filter type.

    - #### setType

          protected void setType(LocaleFilter.FilterType type)

      Helper method. Sets the locale filter type (either None or Any).
      Parameters:
        `type` - None or Any locale filter type.

    - #### isEmpty

          public boolean isEmpty()

      Detects if after construction this locale filter was configured with includeXX(), excludeXX().
      Returns:
        true if the locale filter was not configured after construction.

    - #### fromString

          public LocaleFilter fromString(java.lang.String string)

      Configures this locale filter from a given configuration string.
      Parameters:
        `string` - the given configuration string. The string consists of locale descriptors. The locale descriptors are delimited with a comma or space.

        * -- field mask, can be used in either language, region, or user part fields of a locale descriptor.
        ! -- exclude prefix.
        @ -- regex prefix.
        ^ -- regex flags prefix.

        Examples:

        - all locales except English: !en
        - only English locales except en-nz: en !en-nz
        - all locales except US region: !*-us
        - only locales with "win" as user part: *-*-win
        - regular expression with flags: @e.?-us ^8
      Returns:
        this locale filter.

    - #### toString

          public java.lang.String toString()

      Constructs a configuration string for this locale filter.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the configuration string for this locale filter.

    - #### getExplicitLocaleIds

          public java.util.List<java.lang.String> getExplicitLocaleIds()

      If the filter contains only explicitly listed locales (no regex patterns or masks), then returns the list of locale tags of those locales. If there's at least one mask or pattern, an empty list is returned.
      Returns:
        the list of locale tags.

    - #### getExplicitLocaleIds

          public static java.lang.String getExplicitLocaleIds(java.lang.String string)

      Determines if a given string contains only explicitly listed locales. If the given strin contains only explicitly listed locales (no regex patterns or masks), then returns a string with a space-delimited list of locale tags of those locales. If there's at least one mask or pattern, an empty string is returned.
      Parameters:
        `string` - the given locale filter configuration string. See `fromString(java.lang.String)` for details.
      Returns:
        a string with a space-delimited list of locale tags allowed by this locale filter.