Search documentation of Localize

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

Copy Markdown View Source

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.

## Summary

### Functions

rule_names_for_locale(locale)

Returns the available RBNF rule names for a locale.

to_string(number, rule_name, options \\ [])

Formats a number using RBNF rules.

## Functions

# rule_names_for_locale(locale)

    @spec rule_names_for_locale(atom() | String.t()) ::
      {:ok, [String.t()]} | {:error, Exception.t()}

Returns the available RBNF rule names for a locale.

### Arguments

- `locale` is a locale identifier atom or string.

### Returns

- `{:ok, rule_names}` where `rule_names` is a list of strings.

- `{:error, exception}` if RBNF data is not available.

# to_string(number, rule_name, options \\ [])

    @spec to_string(number() | Decimal.t(), atom() | String.t(), Keyword.t()) ::
      {:ok, String.t()} | {:error, Exception.t()}

Formats a number using RBNF rules.

### Arguments

- `number` is an integer or float.

- `rule_name` is the rule set name atom or string (e.g., `:spellout_cardinal`, `"roman-upper"`). The atoms `:spellout` and `:ordinal` are interpreted specially and map to the best available spellout or ordinal rule for the locale.

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `:en`.

### Returns

- `{:ok, formatted_string}` on success.

- `{:error, exception}` if 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"}