# `Localize.Number.PluralRule.Cardinal`
[🔗](https://github.com/elixir-localize/localize/blob/v1.2.0/lib/localize/number/plural_rules/cardinal.ex#L1)

Implements cardinal plural rules for numbers.

Cardinal plural rules are used for counting quantities
(e.g., "1 item", "2 items", "5 items"). 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 cardinal plural rules
are defined.

### Returns

* A sorted list of locale name atoms.

### Examples

    iex> :en in Localize.Number.PluralRule.Cardinal.available_locale_names()
    true

# `plural_rule`

```elixir
@spec plural_rule(
  number() | Decimal.t(),
  atom() | 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.Cardinal.plural_rule(0, "en")
    :other

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

    iex> Localize.Number.PluralRule.Cardinal.plural_rule(2, "en")
    :other

# `plural_rules`

```elixir
@spec plural_rules() :: %{optional(atom()) => Keyword.t()}
```

Returns all the cardinal plural rules defined in CLDR.

### Returns

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

### Examples

    iex> rules = Localize.Number.PluralRule.Cardinal.plural_rules()
    iex> rules[:en] |> Keyword.keys() |> Enum.sort()
    [:one, :other]

# `plural_rules_for`

```elixir
@spec plural_rules_for(atom() | String.t() | Localize.LanguageTag.t()) ::
  Keyword.t() | nil | {:error, Exception.t()}
```

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, or `nil` if
  the locale has no cardinal plural rules.

* `{:error, exception}` if the locale identifier is invalid.

### Examples

    iex> Localize.Number.PluralRule.Cardinal.plural_rules_for(:en) |> Keyword.keys() |> Enum.sort()
    [:one, :other]

# `pluralize`

```elixir
@spec pluralize(
  number() | Decimal.t(),
  atom() | String.t() | Localize.LanguageTag.t(),
  map()
) :: term()
```

Pluralize a number using cardinal 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.Cardinal.pluralize(1, "en", %{one: "one", other: "other"})
    "one"

    iex> Localize.Number.PluralRule.Cardinal.pluralize(2, "en", %{one: "one", other: "other"})
    "other"

---

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