Unity.Aliases (Unity v1.1.0)

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.

Summary

Functions

all_known_names()

Returns the CLDR base unit names.

known_aliases()

Returns a list of all known alias names.

resolve(name)

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

suggest(name, options \\ [])

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

Functions

all_known_names()

@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()

@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(name)

@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(name, options \\ [])

@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}]