# `Localize.Number.Rbnf`
[🔗](https://github.com/elixir-localize/localize/blob/v0.14.0/lib/localize/number/rbnf.ex#L1)

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.

# `rule_names_for_locale`

```elixir
@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`

```elixir
@spec to_string(number(), 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"`).

* `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"}

---

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