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

English pluralisation, singularisation and spelling-variant rules for CLDR
unit names.

`Unity.Aliases` uses this module in two places. At compile time it calls
`plural/1` for every known CLDR unit to derive a plural alias, so that every
unit which resolves in the singular also resolves in the plural. At run time
it calls `candidates/1` to normalise a form that is not in the derived table
— an SI-prefixed unit such as `milliseconds`, whose singular is assembled by
`Localize.Unit` rather than enumerated, or a British spelling such as
`millilitres`.

The rules are deliberately closed. `candidates/1` only proposes alternative
spellings; the caller must confirm each one is a real unit before accepting
it. Nothing here promotes an arbitrary word to a unit, and in particular
there is no "strip a trailing s and hope" fallback — `bricks` proposes
`brick`, which is not a unit, and so resolves to nothing.

# `candidates`

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

Returns alternative spellings of a unit name to try when it does not resolve
as written.

Combines singularisation with the spelling rewrites, so a British plural of
an SI-prefixed unit such as `"millilitres"` reaches `"milliliter"`.

### Arguments

* `name` - the unit name that failed to resolve.

### Returns

* A list of candidate spellings, most likely first, excluding `name` itself.
  Each candidate must still be confirmed as a real unit by the caller.

### Examples

    iex> Unity.Aliases.Plural.candidates("milliseconds")
    ["millisecond"]

    iex> Unity.Aliases.Plural.candidates("metre")
    ["meter"]

    iex> "millilitres" |> Unity.Aliases.Plural.candidates() |> Enum.member?("milliliter")
    true

    iex> Unity.Aliases.Plural.candidates("bricks")
    ["brick"]

# `plural`

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

Returns the English plural forms of a CLDR unit name.

### Arguments

* `name` - a CLDR unit name such as `"month"` or `"fluid-ounce-imperial"`.

### Returns

* A list of plural spellings, which may be empty for a unit that has no
  distinct plural such as `"hertz"`.

### Examples

    iex> Unity.Aliases.Plural.plural("month")
    ["months"]

    iex> Unity.Aliases.Plural.plural("century")
    ["centuries"]

    iex> Unity.Aliases.Plural.plural("foot")
    ["feet"]

    iex> Unity.Aliases.Plural.plural("fluid-ounce-imperial")
    ["fluid-ounces-imperial"]

    iex> Unity.Aliases.Plural.plural("hertz")
    []

# `singularize`

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

Returns the singular forms to try for a name that looks like a plural.

### Arguments

* `name` - a possibly plural unit name.

### Returns

* A list of candidate singular spellings, which is empty when `name` does not
  look like a plural.

### Examples

    iex> Unity.Aliases.Plural.singularize("months")
    ["month"]

    iex> Unity.Aliases.Plural.singularize("centuries")
    ["century"]

    iex> Unity.Aliases.Plural.singularize("feet")
    ["foot"]

    iex> Unity.Aliases.Plural.singularize("month")
    []

---

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