ICU 76.1: icu::LocaleMatcher::Builder Class Reference

ICU 76.1 76.1

Public Member Functions | Friends
icu::LocaleMatcher::Builder Class Reference

LocaleMatcher builder. More...

`#include <localematcher.h>`

Inheritance diagram for icu::LocaleMatcher::Builder:

## Public Member Functions
| Builder ()
| Constructs a builder used in chaining parameters for building a LocaleMatcher.
| Builder (Builder &&src) noexcept
| Move constructor; might modify the source.
| ~Builder ()
| Destructor.
Builder & | operator= (Builder &&src) noexcept
| Move assignment; might modify the source.
Builder & | setSupportedLocalesFromListString (StringPiece locales)
| Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0.9", and sets the supported locales accordingly.
Builder & | setSupportedLocales (Locale::Iterator &locales)
| Copies the supported locales, preserving iteration order.
template<typename Iter >
Builder & | setSupportedLocales (Iter begin, Iter end)
| Copies the supported locales from the begin/end range, preserving iteration order.
template<typename Iter , typename Conv >
Builder & | setSupportedLocalesViaConverter (Iter begin, Iter end, Conv converter)
| Copies the supported locales from the begin/end range, preserving iteration order.
Builder & | addSupportedLocale (const Locale &locale)
| Adds another supported locale.
Builder & | setNoDefaultLocale ()
| Sets no default locale.
Builder & | setDefaultLocale (const Locale *defaultLocale)
| Sets the default locale; if nullptr, or if it is not set explicitly, then the first supported locale is used as the default locale.
Builder & | setFavorSubtag (ULocMatchFavorSubtag subtag)
| If ULOCMATCH_FAVOR_SCRIPT, then the language differences are smaller than script differences.
Builder & | setDemotionPerDesiredLocale (ULocMatchDemotion demotion)
| Option for whether all desired locales are treated equally or earlier ones are preferred (this is the default).
Builder & | setDirection (ULocMatchDirection matchDirection)
| Option for whether to include or ignore one-way (fallback) match data.
Builder & | setMaxDistance (const Locale &desired, const Locale &supported)
| Sets the maximum distance for an acceptable match.
UBool | copyErrorTo (UErrorCode &outErrorCode) const
| Sets the UErrorCode if an error occurred while setting parameters.
LocaleMatcher | build (UErrorCode &errorCode) const
| Builds and returns a new locale matcher.

## Friends
class | LocaleMatcher

## Detailed Description

LocaleMatcher builder.

Movable but not copyable.

Stable
  ICU 65

Definition at line 301 of file localematcher.h.

## Constructor & Destructor Documentation

## ◆ Builder() [1/2]

icu::LocaleMatcher::Builder::Builder | ( |  | ) |
| inline

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

Returns
  a new Builder object

Stable
  ICU 65

Definition at line 309 of file localematcher.h.

## ◆ Builder() [2/2]

icu::LocaleMatcher::Builder::Builder | ( | Builder && | src | ) |
| noexcept

Move constructor; might modify the source.

This builder will have the same contents that the source builder had.

Parameters

  src | Builder to move contents from.

Stable
  ICU 65

## ◆ ~Builder()

icu::LocaleMatcher::Builder::~Builder | ( |  | ) |

Destructor.

Stable
  ICU 65

## Member Function Documentation

## ◆ addSupportedLocale()

Builder & icu::LocaleMatcher::Builder::addSupportedLocale | ( | const Locale & | locale | ) |

Adds another supported locale.

Duplicates are allowed, and are not removed.

Parameters

  locale | another locale

Returns
  this Builder object

Stable
  ICU 65

## ◆ build()

LocaleMatcher icu::LocaleMatcher::Builder::build | ( | UErrorCode & | errorCode | ) | const

Builds and returns a new locale matcher.

This builder can continue to be used.

Parameters

  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
  LocaleMatcher

Stable
  ICU 65

## ◆ copyErrorTo()

UBool icu::LocaleMatcher::Builder::copyErrorTo | ( | UErrorCode & | outErrorCode | ) | const

Sets the UErrorCode if an error occurred while setting parameters.

Preserves older error codes in the outErrorCode.

Parameters

  outErrorCode | Set to an error code if it does not contain one already and an error occurred while setting parameters. Otherwise unchanged.

Returns
  true if U_FAILURE(outErrorCode)

Stable
  ICU 65

## ◆ operator=()

Builder & icu::LocaleMatcher::Builder::operator= | ( | Builder && | src | ) |
| noexcept

Move assignment; might modify the source.

This builder will have the same contents that the source builder had.

Parameters

  src | Builder to move contents from.

Stable
  ICU 65

## ◆ setDefaultLocale()

Builder & icu::LocaleMatcher::Builder::setDefaultLocale | ( | const Locale * | defaultLocale | ) |

Sets the default locale; if nullptr, or if it is not set explicitly, then the first supported locale is used as the default locale.

There is no default locale at all (nullptr will be returned instead) if setNoDefaultLocale() is called.

Parameters

  defaultLocale | the default locale (will be copied)

Returns
  this Builder object

Stable
  ICU 65

## ◆ setDemotionPerDesiredLocale()

Builder & icu::LocaleMatcher::Builder::setDemotionPerDesiredLocale | ( | ULocMatchDemotion | demotion | ) |

Option for whether all desired locales are treated equally or earlier ones are preferred (this is the default).

Parameters

  demotion | the demotion per desired locale to set.

Returns
  this Builder object

Stable
  ICU 65

## ◆ setDirection()

Builder & icu::LocaleMatcher::Builder::setDirection | ( | ULocMatchDirection | matchDirection | ) |
| inline

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

By default, they are included.

Parameters

  matchDirection | the match direction to set.

Returns
  this Builder object

Stable
  ICU 67

Definition at line 470 of file localematcher.h.

References U_SUCCESS.

## ◆ setFavorSubtag()

Builder & icu::LocaleMatcher::Builder::setFavorSubtag | ( | ULocMatchFavorSubtag | subtag | ) |

If ULOCMATCH_FAVOR_SCRIPT, then the language differences are smaller than script differences.

This is used in situations (such as maps) where it is better to fall back to the same script than a similar language.

Parameters

  subtag | the subtag to favor

Returns
  this Builder object

Stable
  ICU 65

## ◆ setMaxDistance()

Builder & icu::LocaleMatcher::Builder::setMaxDistance | ( | const Locale & | desired,
|  | const Locale & | supported )

Sets the maximum distance for an acceptable match.

The matcher will return a match for a pair of locales only if they match at least as well as the pair given here.

For example, setMaxDistance(en-US, en-GB) limits matches to ones where the (desired, support) locales have a distance no greater than a region subtag difference. This is much stricter than the CLDR default.

The details of locale matching are subject to changes in CLDR data and in the algorithm. Specifying a maximum distance in relative terms via a sample pair of locales insulates from changes that affect all distance metrics similarly, but some changes will necessarily affect relative distances between different pairs of locales.

Parameters

  desired | the desired locale for distance comparison.
  supported | the supported locale for distance comparison.

Returns
  this Builder object

Stable
  ICU 68

## ◆ setNoDefaultLocale()

Builder & icu::LocaleMatcher::Builder::setNoDefaultLocale | ( |  | ) |

Sets no default locale.

There will be no explicit or implicit default locale. If there is no good match, then the matcher will return nullptr for the best supported locale.

Stable
  ICU 68

## ◆ setSupportedLocales() [1/2]

template<typename Iter >

Builder & icu::LocaleMatcher::Builder::setSupportedLocales | ( | Iter | begin,
|  | Iter | end )
| inline

Copies the supported locales from the begin/end range, preserving iteration order.

Clears any previously set/added supported locales first. Duplicates are allowed, and are not removed.

Each of the iterator parameter values must be an input iterator whose value is convertible to const Locale &.

Parameters

  begin | Start of range.
  end | Exclusive end of range.

Returns
  this Builder object

Stable
  ICU 65

Definition at line 374 of file localematcher.h.

References U_FAILURE.

## ◆ setSupportedLocales() [2/2]

Builder & icu::LocaleMatcher::Builder::setSupportedLocales | ( | Locale::Iterator & | locales | ) |

Copies the supported locales, preserving iteration order.

Clears any previously set/added supported locales first. Duplicates are allowed, and are not removed.

Parameters

  locales | the list of locale

Returns
  this Builder object

Stable
  ICU 65

## ◆ setSupportedLocalesFromListString()

Builder & icu::LocaleMatcher::Builder::setSupportedLocalesFromListString | ( | StringPiece | locales | ) |

Parses an Accept-Language string (RFC 2616 Section 14.4), such as "af, en, fr;q=0.9", and sets the supported locales accordingly.

Allows whitespace in more places but does not allow "*". Clears any previously set/added supported locales first.

Parameters

  locales | the Accept-Language string of locales to set

Returns
  this Builder object

Stable
  ICU 65

## ◆ setSupportedLocalesViaConverter()

template<typename Iter , typename Conv >

Builder & icu::LocaleMatcher::Builder::setSupportedLocalesViaConverter | ( | Iter | begin,
|  | Iter | end,
|  | Conv | converter )
| inline

Copies the supported locales from the begin/end range, preserving iteration order.

Calls the converter to convert each *begin to a Locale or const Locale &. Clears any previously set/added supported locales first. Duplicates are allowed, and are not removed.

Each of the iterator parameter values must be an input iterator whose value is convertible to const Locale &.

Parameters

  begin | Start of range.
  end | Exclusive end of range.
  converter | Converter from *begin to const Locale & or compatible.

Returns
  this Builder object

Stable
  ICU 65

Definition at line 399 of file localematcher.h.

References U_FAILURE.

## Friends And Related Symbol Documentation

## ◆ LocaleMatcher

friend class LocaleMatcher
| friend

Definition at line 525 of file localematcher.h.

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

- common/unicode/localematcher.h