Class LocaleMatcher
- java.lang.Object
-
- com.ibm.icu.util.LocaleMatcher
-
public final class LocaleMatcher extends java.lang.Object
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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
LocaleMatcher.Builder
LocaleMatcher Builder.static class
LocaleMatcher.Demotion
Builder option for whether all desired locales are treated equally or earlier ones are preferred.static class
LocaleMatcher.Direction
Builder option for whether to include or ignore one-way (fallback) match data.static class
LocaleMatcher.FavorSubtag
Builder option for whether the language subtag or the script subtag is most important.private static class
LocaleMatcher.LocaleLsrIterator
private static class
LocaleMatcher.LsrIterator
static class
LocaleMatcher.Result
Data for the best-matching pair of a desired and a supported locale.private static class
LocaleMatcher.ULocaleLsrIterator
-
Field Summary
Fields Modifier and Type Field Description private java.util.Locale
defaultLocale
private ULocale
defaultULocale
private int
demotionPerDesiredLocale
private LocaleMatcher.Direction
direction
private static java.util.Locale
EMPTY_LOCALE
private LocaleMatcher.FavorSubtag
favorSubtag
private int[]
supportedIndexes
private java.util.Locale[]
supportedLocales
private LSR[]
supportedLSRs
private int
supportedLSRsLength
private java.util.Map<LSR,java.lang.Integer>
supportedLsrToIndex
private ULocale[]
supportedULocales
private int
thresholdDistance
private static boolean
TRACE_MATCHER
private static java.util.Locale
UND_LOCALE
private static LSR
UND_LSR
private static ULocale
UND_ULOCALE
-
Constructor Summary
Constructors Modifier Constructor Description private
LocaleMatcher(LocaleMatcher.Builder builder)
LocaleMatcher(LocalePriorityList supportedLocales)
Copies the supported locales, preserving iteration order, and constructs a LocaleMatcher.LocaleMatcher(java.lang.String supportedLocales)
Parses the string likeLocalePriorityList
does and constructs a LocaleMatcher for the supported locales parsed from the string.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static LocaleMatcher.Builder
builder()
Returns a builder used in chaining parameters for building a LocaleMatcher.ULocale
canonicalize(ULocale locale)
Partially canonicalizes a locale (language).private LocaleMatcher.Result
defaultResult()
java.util.Locale
getBestLocale(java.lang.Iterable<java.util.Locale> desiredLocales)
Returns the supported locale which best matches one of the desired locales.java.util.Locale
getBestLocale(java.util.Locale desiredLocale)
Returns the supported locale which best matches the desired locale.LocaleMatcher.Result
getBestLocaleResult(java.lang.Iterable<java.util.Locale> desiredLocales)
Returns the best match between the desired and supported locales.LocaleMatcher.Result
getBestLocaleResult(java.util.Locale desiredLocale)
Returns the best match between the desired locale and the supported locales.ULocale
getBestMatch(ULocale desiredLocale)
Returns the supported locale which best matches the desired locale.ULocale
getBestMatch(java.lang.Iterable<ULocale> desiredLocales)
Returns the supported locale which best matches one of the desired locales.ULocale
getBestMatch(java.lang.String desiredLocaleList)
Parses the string likeLocalePriorityList
does and returns the supported locale which best matches one of the desired locales.LocaleMatcher.Result
getBestMatchResult(ULocale desiredLocale)
Returns the best match between the desired locale and the supported locales.LocaleMatcher.Result
getBestMatchResult(java.lang.Iterable<ULocale> desiredLocales)
Returns the best match between the desired and supported locales.private int
getBestSuppIndex(LSR desiredLSR, LocaleMatcher.LsrIterator remainingIter)
private static LSR
getMaximalLsrOrUnd(ULocale locale)
private static LSR
getMaximalLsrOrUnd(java.util.Locale locale)
boolean
isMatch(ULocale desired, ULocale supported)
Returns true if the pair of locales matches acceptably.boolean
isMatch(java.util.Locale desired, java.util.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(java.util.Locale desiredLocale, LocaleMatcher.LocaleLsrIterator lsrIter, int suppIndex)
double
match(ULocale desired, ULocale desiredMax, ULocale supported, ULocale supportedMax)
Deprecated.ICU 65 Build and use a matcher rather than comparing pairs of locales.private int
putIfAbsent(LSR lsr, int i, int suppLength)
java.lang.String
toString()
-
-
-
Field Detail
-
UND_LSR
private static final LSR UND_LSR
-
UND_ULOCALE
private static final ULocale UND_ULOCALE
-
UND_LOCALE
private static final java.util.Locale UND_LOCALE
-
EMPTY_LOCALE
private static final java.util.Locale EMPTY_LOCALE
-
TRACE_MATCHER
private static final boolean TRACE_MATCHER
- See Also:
- Constant Field Values
-
thresholdDistance
private final int thresholdDistance
-
demotionPerDesiredLocale
private final int demotionPerDesiredLocale
-
favorSubtag
private final LocaleMatcher.FavorSubtag favorSubtag
-
direction
private final LocaleMatcher.Direction direction
-
supportedULocales
private final ULocale[] supportedULocales
-
supportedLocales
private final java.util.Locale[] supportedLocales
-
supportedLsrToIndex
private final java.util.Map<LSR,java.lang.Integer> supportedLsrToIndex
-
supportedLSRs
private final LSR[] supportedLSRs
-
supportedIndexes
private final int[] supportedIndexes
-
supportedLSRsLength
private final int supportedLSRsLength
-
defaultULocale
private final ULocale defaultULocale
-
defaultLocale
private final java.util.Locale defaultLocale
-
-
Constructor Detail
-
LocaleMatcher
public LocaleMatcher(LocalePriorityList supportedLocales)
Copies the supported locales, preserving iteration order, and constructs a LocaleMatcher. The first locale is used as the default locale for when there is no good match.- Parameters:
supportedLocales
- list of locales
-
LocaleMatcher
public LocaleMatcher(java.lang.String supportedLocales)
Parses the string likeLocalePriorityList
does and constructs a LocaleMatcher for the supported locales parsed from the string. The first one (in LocalePriorityList iteration order) is used as the default locale for when there is no good match.- Parameters:
supportedLocales
- the string of locales to set, to be parsed like LocalePriorityList does
-
LocaleMatcher
private LocaleMatcher(LocaleMatcher.Builder builder)
-
-
Method Detail
-
builder
public static LocaleMatcher.Builder builder()
Returns a builder used in chaining parameters for building a LocaleMatcher.- Returns:
- a new Builder object
-
putIfAbsent
private final int putIfAbsent(LSR lsr, int i, int suppLength)
-
getMaximalLsrOrUnd
private static final LSR getMaximalLsrOrUnd(java.util.Locale locale)
-
getBestMatch
public ULocale getBestMatch(ULocale desiredLocale)
Returns the supported locale which best matches the desired locale.- Parameters:
desiredLocale
- Typically a user's language.- Returns:
- the best-matching supported locale.
-
getBestMatch
public ULocale getBestMatch(java.lang.Iterable<ULocale> desiredLocales)
Returns the supported locale which best matches one of the desired locales.- Parameters:
desiredLocales
- Typically a user's languages, in order of preference (descending). (In ICU 4.4..63 this parameter had type LocalePriorityList.)- Returns:
- the best-matching supported locale.
-
getBestMatch
public ULocale getBestMatch(java.lang.String desiredLocaleList)
Parses the string likeLocalePriorityList
does and returns the supported locale which best matches one of the desired locales.- Parameters:
desiredLocaleList
- Typically a user's languages, as a string which is to be parsed like LocalePriorityList does.- Returns:
- the best-matching supported locale.
-
getBestLocale
public java.util.Locale getBestLocale(java.util.Locale desiredLocale)
Returns the supported locale which best matches the desired locale.- Parameters:
desiredLocale
- Typically a user's language.- Returns:
- the best-matching supported locale.
-
getBestLocale
public java.util.Locale getBestLocale(java.lang.Iterable<java.util.Locale> desiredLocales)
Returns the supported locale which best matches one of the desired locales.- Parameters:
desiredLocales
- Typically a user's languages, in order of preference (descending).- Returns:
- the best-matching supported locale.
-
defaultResult
private LocaleMatcher.Result defaultResult()
-
makeResult
private LocaleMatcher.Result makeResult(ULocale desiredLocale, LocaleMatcher.ULocaleLsrIterator lsrIter, int suppIndex)
-
makeResult
private LocaleMatcher.Result makeResult(java.util.Locale desiredLocale, LocaleMatcher.LocaleLsrIterator lsrIter, int suppIndex)
-
getBestMatchResult
public LocaleMatcher.Result getBestMatchResult(ULocale desiredLocale)
Returns the best match between the desired locale and the supported locales.- Parameters:
desiredLocale
- Typically a user's language.- Returns:
- the best-matching pair of the desired and a supported locale.
-
getBestMatchResult
public LocaleMatcher.Result getBestMatchResult(java.lang.Iterable<ULocale> desiredLocales)
Returns the best match between the desired and supported locales.- Parameters:
desiredLocales
- Typically a user's languages, in order of preference (descending).- Returns:
- the best-matching pair of a desired and a supported locale.
-
getBestLocaleResult
public LocaleMatcher.Result getBestLocaleResult(java.util.Locale desiredLocale)
Returns the best match between the desired locale and the supported locales.- Parameters:
desiredLocale
- Typically a user's language.- Returns:
- the best-matching pair of the desired and a supported locale.
-
getBestLocaleResult
public LocaleMatcher.Result getBestLocaleResult(java.lang.Iterable<java.util.Locale> desiredLocales)
Returns the best match between the desired and supported locales.- Parameters:
desiredLocales
- Typically a user's languages, in order of preference (descending).- Returns:
- the best-matching pair of a desired and a supported locale.
-
getBestSuppIndex
private int getBestSuppIndex(LSR desiredLSR, LocaleMatcher.LsrIterator remainingIter)
- Parameters:
desiredLSR
- The first desired locale's LSR.remainingIter
- Remaining desired LSRs, null or empty if none.- Returns:
- the index of the best-matching supported locale, or -1 if there is no good match.
-
isMatch
public boolean isMatch(java.util.Locale desired, java.util.Locale supported)
Returns true if the pair of locales matches acceptably. This is influenced by Builder options such as setDirection(), setFavorSubtag(), and setMaxDistance().- Parameters:
desired
- The desired locale.supported
- The supported locale.- Returns:
- true if the pair of locales matches acceptably.
-
isMatch
public boolean isMatch(ULocale desired, ULocale supported)
Returns true if the pair of locales matches acceptably. This is influenced by Builder options such as setDirection(), setFavorSubtag(), and setMaxDistance().- Parameters:
desired
- The desired locale.supported
- The supported locale.- Returns:
- true if the pair of locales matches acceptably.
-
match
@Deprecated public double match(ULocale desired, ULocale desiredMax, ULocale supported, ULocale 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.This is mostly an implementation detail, and the precise values may change over time. The implementation may use either the maximized forms or the others ones, or both. The implementation may or may not rely on the forms to be consistent with each other.
Callers should construct and use a matcher rather than match pairs of locales directly.
- Parameters:
desired
- Desired locale.desiredMax
- Maximized locale (using likely subtags).supported
- Supported locale.supportedMax
- Maximized locale (using likely subtags).- Returns:
- value between 0 and 1, inclusive.
-
canonicalize
public ULocale canonicalize(ULocale locale)
Partially canonicalizes a locale (language). Note that for now, it is canonicalizing according to CLDR conventions (he vs iw, etc), since that is what is needed for likelySubtags.Currently, this is a much simpler canonicalization than what the ULocale class does: The language/script/region subtags are each mapped separately, ignoring the other subtags. If none of these change, then the input locale is returned. Otherwise a new ULocale with only those subtags is returned, removing variants and extensions.
- Parameters:
locale
- language/locale code- Returns:
- ULocale with remapped subtags.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-