Find the desired locale that is the best suported match.

Arguments

• desired is any valid locale name or list of locale names returned by Cldr.known_locale_names/1 or a string or atom locale name.

• options is a keyword list of options.

Options

• :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

• :supported is a list of locale names that are supported by the application. The default is Cldr.known_locale_names/1.

• :threshold filters the returned list to those locales that score below this limit. The default is 50.

Returns

• A possibly empty list of {supported_locale, numeric_score} tuples sorted in ascending numeric score order. The head of the list is considered the best match for desired in supported.

Examples

  iex> Cldr.Locale.Match.best_match "zh-HK",
  ...>   supported: ["zh", "zh-Hans", "zh-Hant", "en", "fr", "en-Hant"]
  {:ok, "zh-Hant", 5}

  iex> supported = Cldr.known_gettext_locale_names()
  ["bg_BG", "en", "en_GB", "es", "it"]
  iex> Cldr.Locale.Match.best_match("en-GB", supported: supported)
  {:ok, "en_GB", 0}
  iex> Cldr.Locale.Match.best_match("zh-HK", supported: supported)
  {:error, {Cldr.NoMatchingLocale, "No match for desired locales \"zh-HK\""}}

Return a match distance between a desired locale and a supported locale.

Arguments

• desired is any valid locale returned by Cldr.known_locale_names/1 or a string or atom locale name.

• supported is any valid locale returned by Cldr.known_locale_names/1 or a string or atom locale name.

• backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

Returns

• A numeric score indicating how well the supported locale can represent the desired locale. A smaller number is better with a value under 10 being a good fit and a number over 50 being a poor fit.

Example

iex> Cldr.Locale.Match.match_distance("en", "en")
0

iex> Cldr.Locale.Match.match_distance("en-AU", "en")
5

iex> Cldr.Locale.Match.match_distance("en-AU", "en-GB")
3

iex> Cldr.Locale.Match.match_distance("zh-HK", "zh-Hant")
5

iex> Cldr.Locale.Match.match_distance("en", "zh-Hans")
134