Top Description Inners Fields Constructors Methods
com.ibm.icu.util

public final Class LocaleMatcher

extends Object
Class Inheritance
Imports
java.util.ArrayList, .Collection, .HashMap, .Iterator, .List, .Locale, .Map, com.ibm.icu.impl.locale.LSR, .LocaleDistance, .XLikelySubtags
Immutable class that picks the best match between a user's desired locales and an application's supported locales.

Example: 

LocaleMatcher matcher = LocaleMatcher.builder().setSupportedLocales("fr, en-GB, en").build();
Locale bestSupported = matcher.getBestLocale(Locale.US);  // "en"

A matcher takes into account when languages are close to one another, such as Danish and Norwegian, and when regional variants are close, like en-GB and en-AU as opposed to en-US.

If there are multiple supported locales with the same (language, script, region) likely subtags, then the current implementation returns the first of those locales. It ignores variant subtags (except for pseudolocale variants) and extensions. This may change in future versions.

For example, the current implementation does not distinguish between de, de-DE, de-Latn, de-1901, de-u-co-phonebk.

If you prefer one equivalent locale over another, then provide only the preferred one, or place it earlier in the list of supported locales.

Otherwise, the order of supported locales may have no effect on the best-match results. The current implementation compares each desired locale with supported locales in the following order: 1. Default locale, if supported; 2. CLDR "paradigm locales" like en-GB and es-419; 3. other supported locales. This may change in future versions.

Often a product will just need one matcher instance, built with the languages that it supports. However, it may want multiple instances with different default languages based on additional information, such as the domain.

This class is not intended for public subclassing.

Author
[email protected]
ICU Status
Stable since ICU 4.4.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
LocaleMatcher.Builder

LocaleMatcher Builder.

public static enum
LocaleMatcher.Demotion

Builder option for whether all desired locales are treated equally or earlier ones are preferred.

public static enum
LocaleMatcher.Direction

Builder option for whether to include or ignore one-way (fallback) match data.

public static enum
LocaleMatcher.FavorSubtag

Builder option for whether the language subtag or the script subtag is most important.

private static class
LocaleMatcher.LocaleLsrIterator

private abstract static class
LocaleMatcher.LsrIterator

public static class
LocaleMatcher.Result

Data for the best-matching pair of a desired and a supported locale.

private static class
LocaleMatcher.ULocaleLsrIterator

Field Summary

Modifier and TypeField and Description
private final Locale
defaultLocale

private final ULocale
defaultULocale

private final int
demotionPerDesiredLocale

private final LocaleMatcher.Direction
direction

private static final Locale
EMPTY_LOCALE

private final LocaleMatcher.FavorSubtag
favorSubtag

private final int[]
supportedIndexes

private final Locale[]
supportedLocales

private final LSR[]
supportedLSRs

private final int
supportedLSRsLength

private final Map<LSR, Integer>
supportedLsrToIndex

private final ULocale[]
supportedULocales

private final int
thresholdDistance

private static final boolean
TRACE_MATCHER

private static final Locale
UND_LOCALE

private static final LSR
UND_LSR

private static final ULocale
UND_ULOCALE

Constructor Summary

AccessConstructor and Description
public
LocaleMatcher(LocalePriorityList
list of locales
supportedLocales)

Copies the supported locales, preserving iteration order, and constructs a LocaleMatcher.

public
LocaleMatcher(String
the string of locales to set, to be parsed like LocalePriorityList does
supportedLocales)

Parses the string like LocalePriorityList does and constructs a LocaleMatcher for the supported locales parsed from the string.

private
LocaleMatcher(LocaleMatcher.Builder builder)

Method Summary

Modifier and TypeMethod and Description
public static LocaleMatcher.Builder

Returns:

a new Builder object
builder()

Returns a builder used in chaining parameters for building a LocaleMatcher.

public ULocale

Returns:

ULocale with remapped subtags.
canonicalize(ULocale
language/locale code
locale)

Partially canonicalizes a locale (language).

private LocaleMatcher.Result
defaultResult()

public Locale

Returns:

the best-matching supported locale.
getBestLocale(Locale
Typically a user's language.
desiredLocale)

Returns the supported locale which best matches the desired locale.

public Locale

Returns:

the best-matching supported locale.
getBestLocale(Iterable<Locale>
Typically a user's languages, in order of preference (descending).
desiredLocales)

Returns the supported locale which best matches one of the desired locales.

public LocaleMatcher.Result

Returns:

the best-matching pair of the desired and a supported locale.
getBestLocaleResult(Locale
Typically a user's language.
desiredLocale)

Returns the best match between the desired locale and the supported locales.

public LocaleMatcher.Result

Returns:

the best-matching pair of a desired and a supported locale.
getBestLocaleResult(Iterable<Locale>
Typically a user's languages, in order of preference (descending).
desiredLocales)

Returns the best match between the desired and supported locales.

public ULocale

Returns:

the best-matching supported locale.
getBestMatch(ULocale
Typically a user's language.
desiredLocale)

Returns the supported locale which best matches the desired locale.

public ULocale

Returns:

the best-matching supported locale.
getBestMatch(Iterable<ULocale>
Typically a user's languages, in order of preference (descending). (In ICU 4.4..63 this parameter had type LocalePriorityList.)
desiredLocales)

Returns the supported locale which best matches one of the desired locales.

public ULocale

Returns:

the best-matching supported locale.
getBestMatch(String
Typically a user's languages, as a string which is to be parsed like LocalePriorityList does.
desiredLocaleList)

Parses the string like LocalePriorityList does and returns the supported locale which best matches one of the desired locales.

public LocaleMatcher.Result

Returns:

the best-matching pair of the desired and a supported locale.
getBestMatchResult(ULocale
Typically a user's language.
desiredLocale)

Returns the best match between the desired locale and the supported locales.

public LocaleMatcher.Result

Returns:

the best-matching pair of a desired and a supported locale.
getBestMatchResult(Iterable<ULocale>
Typically a user's languages, in order of preference (descending).
desiredLocales)

Returns the best match between the desired and supported locales.

private int

Returns:

the index of the best-matching supported locale, or -1 if there is no good match.
getBestSuppIndex(LSR
The first desired locale's LSR.
desiredLSR, LocaleMatcher.LsrIterator
Remaining desired LSRs, null or empty if none.
remainingIter)

private static final LSR
getMaximalLsrOrUnd(ULocale locale)

private static final LSR
getMaximalLsrOrUnd(Locale locale)

public boolean

Returns:

true if the pair of locales matches acceptably.
isMatch(Locale
The desired locale.
desired, Locale
The supported locale.
supported)

Returns true if the pair of locales matches acceptably.

public boolean

Returns:

true if the pair of locales matches acceptably.
isMatch(ULocale
The desired locale.
desired, ULocale
The supported locale.
supported)

Returns true if the pair of locales matches acceptably.

private LocaleMatcher.Result
makeResult(ULocale desiredLocale, LocaleMatcher.ULocaleLsrIterator lsrIter, int suppIndex)

private LocaleMatcher.Result
makeResult(Locale desiredLocale, LocaleMatcher.LocaleLsrIterator lsrIter, int suppIndex)

public double

Returns:

value between 0 and 1, inclusive.
match(ULocale
Desired locale.
desired, ULocale
Maximized locale (using likely subtags).
desiredMax, ULocale
Supported locale.
supported, ULocale
Maximized locale (using likely subtags).
supportedMax)

Deprecated ICU 65 Build and use a matcher rather than comparing pairs of locales.
Returns a fraction between 0 and 1, where 1 means that the languages are a perfect match, and 0 means that they are completely different.
private final int
putIfAbsent(LSR lsr, int i, int suppLength)

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait