Localize.Number.PluralRule.Ordinal (Localize v0.46.0)

Copy Markdown View Source

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.

Summary

Functions

available_locale_names()

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

plural_rule(number, locale, rounding \\ Math.default_rounding())

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

plural_rules()

Returns all the ordinal plural rules defined in CLDR.

plural_rules_for(locale_name)

Return the plural rules for a locale.

pluralize(number, locale_name, substitutions)

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

Functions

available_locale_names()

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

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

Returns

  • A sorted list of locale name atoms.

Examples

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

plural_rule(number, locale, rounding \\ Math.default_rounding())

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

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

Returns all the ordinal plural rules defined in CLDR.

Returns

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

Examples

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

plural_rules_for(locale_name)

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

Return the plural rules for a locale.

Arguments

Returns

  • A keyword list of {category, parsed_rule} pairs, or nil if the locale has no ordinal plural rules.

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

Examples

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

pluralize(number, locale_name, substitutions)

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

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 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"