Immutable class that picks the best match between a user's desired locales and an application's supported locales. More...

#include <localematcher.h>

Inheritance diagram for icu::LocaleMatcher:

Data Structures
class	Builder
	LocaleMatcher builder. More...

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

Public Member Functions
	LocaleMatcher (LocaleMatcher &&src) U_NOEXCEPT
	Move copy constructor; might modify the source. More...

	~LocaleMatcher ()
	Destructor. More...

LocaleMatcher &	operator= (LocaleMatcher &&src) U_NOEXCEPT
	Move assignment operator; might modify the source. More...

const Locale *	getBestMatch (const Locale &desiredLocale, UErrorCode &errorCode) const
	Returns the supported locale which best matches the desired locale. More...

const Locale *	getBestMatch (Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
	Returns the supported locale which best matches one of the desired locales. More...

const Locale *	getBestMatchForListString (StringPiece desiredLocaleList, UErrorCode &errorCode) const
	Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0.9", and returns the supported locale which best matches one of the desired locales. More...

Result	getBestMatchResult (const Locale &desiredLocale, UErrorCode &errorCode) const
	Returns the best match between the desired locale and the supported locales. More...

Result	getBestMatchResult (Locale::Iterator &desiredLocales, UErrorCode &errorCode) const
	Returns the best match between the desired and supported locales. More...

UBool	isMatch (const Locale &desired, const Locale &supported, UErrorCode &errorCode) const
	Returns true if the pair of locales matches acceptably. More...

double	internalMatch (const Locale &desired, const Locale &supported, UErrorCode &errorCode) const
	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. More...

Detailed Description

Immutable class that picks the best match between a user's desired locales and an application's supported locales.

Movable but not copyable.

Example:

UErrorCode errorCode = U_ZERO_ERROR;
LocaleMatcher matcher = LocaleMatcher::Builder().setSupportedLocales("fr, en-GB, en").build(errorCode);
Locale *bestSupported = matcher.getBestLocale(Locale.US, errorCode);  // "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:

Default locale, if supported;
CLDR "paradigm locales" like en-GB and es-419;
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.

Stable:: ICU 65

Definition at line 184 of file localematcher.h.

Constructor & Destructor Documentation

◆ LocaleMatcher()

icu::LocaleMatcher::LocaleMatcher ( LocaleMatcher && src )

Move copy constructor; might modify the source.

This matcher will have the same settings that the source matcher had.

Parameters

src	source matcher

Stable:: ICU 65

◆ ~LocaleMatcher()

icu::LocaleMatcher::~LocaleMatcher ( )

Destructor.

Stable:: ICU 65

Member Function Documentation

◆ getBestMatch() [1/2]

const Locale * icu::LocaleMatcher::getBestMatch	(	const Locale &	desiredLocale,
		UErrorCode &	errorCode
	)		const

Returns the supported locale which best matches the desired locale.

Parameters

desiredLocale	Typically a user's language.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: the best-matching supported locale.

Stable:: ICU 65

◆ getBestMatch() [2/2]

const Locale * icu::LocaleMatcher::getBestMatch	(	Locale::Iterator &	desiredLocales,
		UErrorCode &	errorCode
	)		const

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

Parameters

desiredLocales	Typically a user's languages, in order of preference (descending).
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: the best-matching supported locale.

Stable:: ICU 65

◆ getBestMatchForListString()

const Locale * icu::LocaleMatcher::getBestMatchForListString	(	StringPiece	desiredLocaleList,
		UErrorCode &	errorCode
	)		const

Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0.9", and returns the supported locale which best matches one of the desired locales.

Allows whitespace in more places but does not allow "*".

Parameters

desiredLocaleList	Typically a user's languages, as an Accept-Language string.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: the best-matching supported locale.

Stable:: ICU 65

◆ getBestMatchResult() [1/2]

Result icu::LocaleMatcher::getBestMatchResult	(	const Locale &	desiredLocale,
		UErrorCode &	errorCode
	)		const

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

If the result's desired locale is not nullptr, then it is the address of the input locale. It has not been cloned.

Parameters

desiredLocale	Typically a user's language.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: the best-matching pair of the desired and a supported locale.

Stable:: ICU 65

◆ getBestMatchResult() [2/2]

Result icu::LocaleMatcher::getBestMatchResult	(	Locale::Iterator &	desiredLocales,
		UErrorCode &	errorCode
	)		const

Returns the best match between the desired and supported locales.

If the result's desired locale is not nullptr, then it is a clone of the best-matching desired locale. The Result object owns the clone.

Parameters

desiredLocales	Typically a user's languages, in order of preference (descending).
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: the best-matching pair of a desired and a supported locale.

Stable:: ICU 65

◆ internalMatch()

double icu::LocaleMatcher::internalMatch	(	const Locale &	desired,
		const Locale &	supported,
		UErrorCode &	errorCode
	)		const

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.
supported	Supported locale.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: value between 0 and 1, inclusive.

Internal:: Do not use. This API is for internal use only. (has a known user)

◆ isMatch()

UBool icu::LocaleMatcher::isMatch	(	const Locale &	desired,
		const Locale &	supported,
		UErrorCode &	errorCode
	)		const

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.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: true if the pair of locales matches acceptably.

Stable:: ICU 68

◆ operator=()

LocaleMatcher & icu::LocaleMatcher::operator= ( LocaleMatcher && src )

Move assignment operator; might modify the source.

This matcher will have the same settings that the source matcher had. The behavior is undefined if *this and src are the same object.

Parameters

src	source matcher

Returns: *this

Stable:: ICU 65

The documentation for this class was generated from the following file:

localematcher.h

Data Structures

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LocaleMatcher()

◆ ~LocaleMatcher()

Member Function Documentation

◆ getBestMatch() [1/2]

◆ getBestMatch() [2/2]

◆ getBestMatchForListString()

◆ getBestMatchResult() [1/2]

◆ getBestMatchResult() [2/2]

◆ internalMatch()

◆ isMatch()

◆ operator=()