# `Unity.Aliases`
[🔗](https://github.com/elixir-localize/unity/blob/v1.1.0/lib/unity/aliases.ex#L1)

Maps user-friendly unit abbreviations and common names to CLDR unit identifiers
recognized by `Localize.Unit`.

The alias table is built at compile time from a hand-curated abbreviation map
plus a plural for every CLDR unit, derived by `Unity.Aliases.Plural`. Deriving
the plurals rather than listing them keeps the table in step with the unit
data: every unit that resolves in the singular also resolves in the plural,
and a unit added to CLDR gets its plural without an edit here.

Resolution tries, in order, the hand-written aliases, the name as a CLDR unit
name, the derived plurals, and `Localize.Unit.new/1`. A name that still does
not resolve is retried through the spelling rules in `Unity.Aliases.Plural`,
which cover forms too numerous to enumerate — the plural of an SI-prefixed
unit such as `milliseconds`, and British spellings such as `millilitres`.

A retried spelling is accepted only if it is itself a known unit, so an
ordinary English word is never promoted to a unit.

# `all_known_names`

```elixir
@spec all_known_names() :: [String.t()]
```

Returns the CLDR base unit names.

These are the names `Localize.Unit` enumerates by category. Aliases, derived
plurals and SI-prefixed forms such as `kilometer` are not among them; use
`known_aliases/0` for the alias table, or `resolve/1` to resolve an arbitrary
spelling.

### Returns

* A list of CLDR base unit names.

### Examples

    iex> "meter" in Unity.Aliases.all_known_names()
    true

    iex> "kilometer" in Unity.Aliases.all_known_names()
    false

# `known_aliases`

```elixir
@spec known_aliases() :: [String.t()]
```

Returns a list of all known alias names.

Includes the hand-written abbreviations and the plurals derived from the CLDR
unit list, but not the spellings normalised at resolution time, which are not
an enumerable set.

### Returns

* A list of alias names, each of which resolves via `resolve/1`.

### Examples

    iex> "km" in Unity.Aliases.known_aliases()
    true

    iex> "months" in Unity.Aliases.known_aliases()
    true

# `resolve`

```elixir
@spec resolve(term()) :: {:ok, String.t()} | {:error, :unknown_unit}
```

Resolves a user-provided unit name to a CLDR unit identifier.

Tries the alias table first, then the name as a CLDR unit name, then the
derived plural table. A name that still does not resolve is retried through
the spelling rules in `Unity.Aliases.Plural`, which cover the plural of an
SI-prefixed unit such as `milliseconds` and British spellings such as
`millilitres`. Returns `{:ok, cldr_name}` or `{:error, :unknown_unit}`.

A retried spelling is only accepted if it is itself a known unit, so an
ordinary word is never promoted to a unit: `bricks` proposes `brick`, which
is not a unit, and the call returns an error.

### Arguments

* `name` - a string unit name or abbreviation.

### Returns

* `{:ok, cldr_name}` if the name resolves to a known unit.

* `{:error, :unknown_unit}` if the name cannot be resolved.

### Examples

    iex> Unity.Aliases.resolve("km")
    {:ok, "kilometer"}

    iex> Unity.Aliases.resolve("meter")
    {:ok, "meter"}

    iex> Unity.Aliases.resolve("months")
    {:ok, "month"}

    iex> Unity.Aliases.resolve("milliseconds")
    {:ok, "millisecond"}

    iex> Unity.Aliases.resolve("frobnicator")
    {:error, :unknown_unit}

# `suggest`

```elixir
@spec suggest(
  String.t(),
  keyword()
) :: [{String.t(), float()}]
```

Finds the closest matching unit names for a given unknown name using
Jaro distance for fuzzy matching.

### Arguments

* `name` - the unknown unit name to match against.

* `options` - keyword list of options.

### Options

* `:max_results` - maximum number of suggestions to return. Defaults to 5.

* `:threshold` - minimum Jaro distance to include. Defaults to 0.7.

### Returns

A list of `{cldr_name, distance}` tuples, sorted by distance descending and
then by name. Each unit appears once, under its CLDR name, scored by its
closest-matching spelling.

### Examples

    iex> Unity.Aliases.suggest("metrs", max_results: 1)
    [{"meter", 0.9444444444444445}]

    iex> Unity.Aliases.suggest("secnd", max_results: 2)
    [{"second", 0.9444444444444445}, {"decade", 0.7000000000000001}]

---

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