Search documentation of Localize

# Localize.Number.PluralRule (Localize v0.39.0)

Copy Markdown View Source

Defines plural rule modules for cardinal and ordinal number categories according to the CLDR plural rules specification.

At compile time, this module generates two child modules:

- `Localize.Number.PluralRule.Cardinal` — implements cardinal plural rules (used for counting: "1 item", "2 items").

- `Localize.Number.PluralRule.Ordinal` — implements ordinal plural rules (used for ordering: "1st", "2nd", "3rd").

Each generated module contains per-locale `plural_rule/2` functions that classify a number into one of the CLDR plural categories: `:zero`, `:one`, `:two`, `:few`, `:many`, or `:other`.

## Summary

### Types

operand()
plural_rule()

A plural rule definition before compilation.

plural_type()

The plural categories into which a number can be classified.

### Functions

known_plural_types()

Returns the list of possible plural categories.

plural_type(number, options \\ [])

Returns the plural category for a given number.

## Types

# operand()

    @type operand() :: any()

# plural_rule()

    @type plural_rule() :: Keyword.t()

A plural rule definition before compilation.

# plural_type()

    @type plural_type() :: :zero | :one | :two | :few | :many | :other

The plural categories into which a number can be classified.

## Functions

# known_plural_types()

    @spec known_plural_types() :: [plural_type(), ...]

Returns the list of possible plural categories.

### Returns

- A list of plural type atoms.

### Examples

    iex> Localize.Number.PluralRule.known_plural_types()
    [:zero, :one, :two, :few, :many, :other]

# plural_type(number, options \\ [])

    @spec plural_type(number() | Decimal.t(), Keyword.t()) ::
      plural_type() | {:error, Exception.t()}

Returns the plural category for a given number.

### Arguments

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

- `options` is a keyword list of options.

### Options

- `:locale` is any locale identifier string or a `Localize.LanguageTag.t/0`. The default is `"en"`.

- `:type` is either `:cardinal` or `:ordinal`. The default is `:cardinal`.

### Returns

- A plural category atom: `:zero`, `:one`, `:two`, `:few`, `:many`, or `:other`.

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

### Examples

    iex> Localize.Number.PluralRule.plural_type(1, locale: "en")
    :one

    iex> Localize.Number.PluralRule.plural_type(2, locale: "en")
    :other

    iex> Localize.Number.PluralRule.plural_type(1, locale: "en", type: :ordinal)
    :one

    iex> Localize.Number.PluralRule.plural_type(2, locale: "en", type: :ordinal)
    :two