# `Cldr.Locale.Match`
[🔗](https://github.com/elixir-cldr/cldr/blob/v2.47.3/lib/cldr/locale/match.ex#L1)

Implements the [CLDR language matching algorithm](https://www.unicode.org/reports/tr35/tr35.html#LanguageMatching).

# `best_match`
*since 2.44.0* 

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 54.

### 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\""}}

# `match_distance`
*since 2.44.0* 

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*