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

Functions for formatting numbers in a locale-aware manner.

This module provides the primary public API for converting
numbers to localized string representations, including
standard decimal formatting, currency formatting, percentage
formatting, and scientific notation.

All formatting is driven by CLDR locale data accessed at
runtime via the locale provider.

# `parse`

Parses a string to a number in a locale-aware manner.

Delegates to `Localize.Number.Parser.parse/2`.

### Arguments

* `string` is any string.

* `options` is a keyword list of options.

### Returns

* `{:ok, number}` or `{:error, exception}`.

# `resolve_currencies`

Resolves currencies from strings within a list.

Delegates to `Localize.Number.Parser.resolve_currencies/2`.

# `resolve_currency`

Resolves a currency from a string.

Delegates to `Localize.Number.Parser.resolve_currency/2`.

# `resolve_per`

Resolves percent or permille from a string.

Delegates to `Localize.Number.Parser.resolve_per/2`.

# `resolve_pers`

Resolves percent and permille symbols from strings within a list.

Delegates to `Localize.Number.Parser.resolve_pers/2`.

# `scan`

Scans a string and returns a list of strings and numbers.

Delegates to `Localize.Number.Parser.scan/2`.

### Arguments

* `string` is any string.

* `options` is a keyword list of options.

### Returns

* A list of strings and numbers.

# `to_approximately_string`

```elixir
@spec to_approximately_string(number() | Decimal.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Formats a number with the locale's approximately pattern.

Produces strings like `"~5"` (English) or `"約 5"` (Japanese).

### Arguments

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

* `options` is a keyword list of options accepted by
  `to_string/2`.

### Returns

* `{:ok, formatted}` on success.

* `{:error, exception}` if formatting fails.

### Examples

    iex> Localize.Number.to_approximately_string(5, locale: :en)
    {:ok, "~5"}

# `to_at_least_string`

```elixir
@spec to_at_least_string(number() | Decimal.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Formats a number with the locale's "at least" pattern.

Produces strings like `"5+"` (English) or `"5以上"` (Japanese).

### Arguments

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

* `options` is a keyword list of options accepted by
  `to_string/2`.

### Returns

* `{:ok, formatted}` on success.

* `{:error, exception}` if formatting fails.

### Examples

    iex> Localize.Number.to_at_least_string(5, locale: :en)
    {:ok, "5+"}

# `to_at_most_string`

```elixir
@spec to_at_most_string(number() | Decimal.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Formats a number with the locale's "at most" pattern.

Produces strings like `"≤5"` (English) or `"5以下"` (Japanese).

### Arguments

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

* `options` is a keyword list of options accepted by
  `to_string/2`.

### Returns

* `{:ok, formatted}` on success.

* `{:error, exception}` if formatting fails.

### Examples

    iex> Localize.Number.to_at_most_string(5, locale: :en)
    {:ok, "≤5"}

# `to_range_string`

```elixir
@spec to_range_string(Range.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Formats a numeric range as a localized string.

Accepts either two numbers or an Elixir `Range`. Uses the
locale's range pattern (e.g., `"3–5"` in English, `"3～5"` in
Japanese) to combine two formatted numbers. When the start and
end are equal, the locale's approximately pattern is used
instead (e.g., `"~5"`).

### Arguments

* `number_start` is the start of the range (integer, float,
  or Decimal).

* `number_end` is the end of the range (integer, float, or
  Decimal).

* `options` is a keyword list of options.

Alternatively:

* `range` is an Elixir `t:Range.t/0` (e.g., `3..5`).

* `options` is a keyword list of options.

### Options

All options accepted by `to_string/2` are supported and applied
to both numbers. Additional options:

* `:approximate` is a boolean. When `true`, forces use of the
  approximately pattern regardless of whether start equals end.
  The default is `false`.

### Returns

* `{:ok, formatted_range}` on success.

* `{:error, exception}` if formatting fails.

### Examples

    iex> Localize.Number.to_range_string(3, 5, locale: :en)
    {:ok, "3–5"}

    iex> Localize.Number.to_range_string(3..5, locale: :en)
    {:ok, "3–5"}

    iex> Localize.Number.to_range_string(5, 5, locale: :en)
    {:ok, "~5"}

# `to_range_string`

```elixir
@spec to_range_string(number() | Decimal.t(), number() | Decimal.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

# `to_range_string!`

```elixir
@spec to_range_string!(Range.t(), Keyword.t()) :: String.t()
```

Same as `to_range_string/3` but raises on error.

### Examples

    iex> Localize.Number.to_range_string!(3, 5, locale: :en)
    "3–5"

    iex> Localize.Number.to_range_string!(3..5, locale: :en)
    "3–5"

# `to_range_string!`

```elixir
@spec to_range_string!(number() | Decimal.t(), number() | Decimal.t(), Keyword.t()) ::
  String.t()
```

# `to_ratio_string`

```elixir
@spec to_ratio_string(number() | Decimal.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Formats a number as a rational fraction string.

Converts a decimal number to its rational fraction representation
using the continued fraction algorithm, then formats it with CLDR
rational format patterns.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is `Localize.get_locale()`.

* `:prefer` is a list of rendering preferences. Valid values are `:default`, `:super_sub`, and `:precomposed`. The default is `[:default]`.

* `:max_denominator` is the largest permitted denominator. The default is `10`.

* `:max_iterations` is the maximum continued fraction iterations. The default is `20`.

* `:epsilon` is the tolerance for float comparisons. The default is `1.0e-10`.

### Returns

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

* `{:error, exception}` if the number cannot be converted to a ratio or locale data is unavailable.

### Examples

    iex> Localize.Number.to_ratio_string(0.5)
    {:ok, "1⁄2"}

    iex> Localize.Number.to_ratio_string(0.5, prefer: [:precomposed])
    {:ok, "½"}

    iex> Localize.Number.to_ratio_string(0.5, prefer: [:super_sub])
    {:ok, "¹⁄₂"}

    iex> Localize.Number.to_ratio_string(1.5)
    {:ok, "1 1⁄2"}

    iex> Localize.Number.to_ratio_string(1.5, prefer: [:super_sub, :precomposed])
    {:ok, "1⁠½"}

# `to_ratio_string!`

```elixir
@spec to_ratio_string!(number() | Decimal.t(), Keyword.t()) :: String.t()
```

Same as `to_ratio_string/2` but raises on error.

### Arguments

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

* `options` is a keyword list of options.

### Returns

* The formatted ratio string.

### Raises

* Raises an exception if the number cannot be converted.

# `to_string`

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

Formats a number as a localized string.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier atom, string, or a
  `t:Localize.LanguageTag.t/0`. The default is `:en`.

* `:number_system` is a number system name or type atom.
  The default is `:default`.

* `:format` is a format style atom or a format pattern string.
  The default is `:standard`. Common styles include `:standard`,
  `:currency`, `:accounting`, `:percent`, `:scientific`,
  `:decimal_short`, `:decimal_long`.

* `:currency` is a currency code atom (e.g., `:USD`). When
  provided, currency formatting is applied.

* `:rounding_mode` is one of `:down`, `:half_up`, `:half_even`,
  `:ceiling`, `:floor`, `:half_down`, `:up`. The default is
  `:half_even`.

* `:fractional_digits` is an integer that sets both the minimum
  and maximum fractional digits to the same value. Equivalent to
  setting `:min_fractional_digits` and `:max_fractional_digits`
  to the same integer. Overridden by either of those options when
  they are also provided.

* `:min_fractional_digits` is an integer specifying the minimum
  number of fractional digits. Trailing zeros are added to reach
  this count. When not set, falls back to `:fractional_digits`
  or the format pattern default.

* `:max_fractional_digits` is an integer specifying the maximum
  number of fractional digits. Values are rounded to fit. When
  not set, falls back to `:fractional_digits` or the format
  pattern default.

* `:maximum_integer_digits` is an integer specifying the maximum
  number of integer digits to display.

* `:wrapper` is a function of arity 2 that wraps formatted
  components. Useful for adding HTML markup.

### Returns

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

* `{:error, exception}` if options are invalid or formatting fails.

### Examples

    iex> Localize.Number.to_string(1234)
    {:ok, "1,234"}

    iex> Localize.Number.to_string(1234.5, locale: :en)
    {:ok, "1,234.5"}

    iex> Localize.Number.to_string(0.56, format: :percent, locale: :en)
    {:ok, "56%"}

# `to_string!`

```elixir
@spec to_string!(number() | Decimal.t(), Keyword.t()) :: String.t()
```

Same as `to_string/2` but raises on error.

### Arguments

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

* `options` is a keyword list of options.

### Returns

* A formatted string.

### Raises

* Raises an exception if formatting fails.

### Examples

    iex> Localize.Number.to_string!(1234)
    "1,234"

---

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