Rules-Based Number Formatting (RBNF) for algorithmic number systems and spellout forms.
RBNF provides formatting for number systems that don't have simple digit-to-digit mappings, such as Roman numerals, Hebrew numerals, Chinese numerals, and spellout forms like "one hundred twenty-three".
RBNF rules are loaded from locale data at runtime and interpreted
by an internal rule processor. Parsed rule ASTs are cached in
:persistent_term for performance.
Where a rule set is looked for
A rule set is looked for in the locale's own data, then in each
parent's in turn, and last in the root locale und, whose rules
write Roman, Hebrew and other numerals. A locale without a
spellout rule set gets an Localize.UnknownRbnfRuleError rather
than root's digit stubs, so a number is never spelled in another
language's words.
CLDR keeps some locales' rules in a parent: Norwegian's spellout
rules are in no, the parent of nb and nn, and en-GB has
none of its own and takes English's from en. A parent's rules
are reached only when the parent is a supported locale, since
only a supported locale's data is installed. An application
whose supported_locales names nb or en-GB lists no or
en as well to spell numbers out in them. Until it does, the
Localize.UnknownRbnfRuleError names that parent in its
:rules_in field and its message.
Summary
Functions
@spec rule_names_for_locale(Localize.locale() | String.t()) :: {:ok, [String.t()]} | {:error, Exception.t()}
Returns the available RBNF rule names for a locale.
Arguments
localeis a locale identifier atom or string.
Returns
{:ok, rule_names}whererule_namesis a sorted list of strings.{:error, exception}if RBNF data is not available.
Examples
iex> {:ok, names} = Localize.Number.Rbnf.rule_names_for_locale(:en)
iex> "spellout_cardinal" in names
true
iex> {:ok, names} = Localize.Number.Rbnf.rule_names_for_locale(:en)
iex> "digits_ordinal" in names
true@spec to_string(number() | Decimal.t(), atom() | String.t(), Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
Formats a number using RBNF rules.
Arguments
numberis an integer or float.rule_nameis the rule set name atom or string (e.g.,:spellout_cardinal,"roman-upper"). The atoms:spelloutand:ordinalare interpreted specially and map to the best available spellout or ordinal rule for the locale.optionsis a keyword list of options.
Options
:localeis a locale identifier. The default is:en.
Returns
{:ok, formatted_string}on success.{:error, exception}if the number, rule name or options are not valid, or the rules are not available.
Examples
iex> Localize.Number.Rbnf.to_string(123, :spellout_cardinal, locale: :en)
{:ok, "one hundred twenty-three"}
iex> Localize.Number.Rbnf.to_string(1, :spellout, locale: :en)
{:ok, "one"}
iex> Localize.Number.Rbnf.to_string(1, :ordinal, locale: :en)
{:ok, "1st"}