# `Localize.Number.PluralRule.Ordinal`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.0/lib/localize/number/plural_rules/ordinal.ex#L1)

Implements ordinal plural rules for numbers.

Ordinal plural rules are used for ordering sequences
(e.g., "1st", "2nd", "3rd", "4th"). Each locale has its
own set of rules that classify a number into one of the
plural categories: `:zero`, `:one`, `:two`, `:few`,
`:many`, or `:other`.

All plural rule functions are generated at compile time
from the CLDR plural rules data.

# `available_locale_names`

```elixir
@spec available_locale_names() :: [atom(), ...]
```

Returns the locale names for which ordinal plural rules
are defined.

### Returns

* A sorted list of locale name atoms.

# `plural_rule`

```elixir
@spec plural_rule(
  number() | Decimal.t(),
  String.t() | Localize.LanguageTag.t(),
  pos_integer()
) :: Localize.Number.PluralRule.plural_type() | {:error, Exception.t()}
```

Return the plural category for a given number in a given locale.

Returns which plural category (`:zero`, `:one`, `:two`, `:few`,
`:many`, or `:other`) a given number belongs to within the
context of a given locale.

### Arguments

* `number` is any integer, float, or Decimal.

* `locale` is a locale name string or a
  `t:Localize.LanguageTag.t/0`.

* `rounding` is a positive integer specifying the number of
  fractional digits to consider. The default is `3`.

### Returns

* A plural category atom.

* `{:error, exception}` if no plural rules are available
  for the locale.

### Examples

    iex> Localize.Number.PluralRule.Ordinal.plural_rule(1, "en")
    :one

    iex> Localize.Number.PluralRule.Ordinal.plural_rule(2, "en")
    :two

    iex> Localize.Number.PluralRule.Ordinal.plural_rule(3, "en")
    :few

    iex> Localize.Number.PluralRule.Ordinal.plural_rule(4, "en")
    :other

# `plural_rules`

Returns all the ordinal plural rules defined in CLDR.

### Returns

* A map of locale names to their parsed plural rule definitions.

# `plural_rules_for`

Return the plural rules for a locale.

### Arguments

* `locale` is a locale name string or atom, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* A keyword list of `{category, parsed_rule}` pairs.

# `pluralize`

Pluralize a number using ordinal plural rules and a
substitution map.

### Arguments

* `number` is an integer, float, or Decimal.

* `locale` is a locale name string or atom, or a
  `t:Localize.LanguageTag.t/0`.

* `substitutions` is a map that maps plural categories to
  substitution values. The valid keys are `:zero`, `:one`,
  `:two`, `:few`, `:many`, and `:other`.

### Returns

* The substitution value for the plural category of the
  given number, or `nil` if no matching substitution is found.

### Examples

    iex> Localize.Number.PluralRule.Ordinal.pluralize(1, "en", %{one: "st", two: "nd", few: "rd", other: "th"})
    "st"

    iex> Localize.Number.PluralRule.Ordinal.pluralize(2, "en", %{one: "st", two: "nd", few: "rd", other: "th"})
    "nd"

---

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