Search documentation of Localize

# Localize.Number (Localize v0.39.0)

Copy Markdown View Source

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.

## Summary

### Functions

parse(string, options \\ [])

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

resolve_currencies(list, options \\ [])

Resolves currencies from strings within a list.

resolve_currency(string, options \\ [])

Resolves a currency from a string.

resolve_per(string, options \\ [])

Resolves percent or permille from a string.

resolve_pers(list, options \\ [])

Resolves percent and permille symbols from strings within a list.

scan(string, options \\ [])

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

to_approximately_string(number, options \\ [])

Formats a number with the locale's approximately pattern.

to_at_least_string(number, options \\ [])

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

to_at_most_string(number, options \\ [])

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

to_range_string(range, options)

Formats a numeric range as a localized string.

to_range_string(number_start, number_end, options \\ [])
to_range_string!(range, options)

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

to_range_string!(number_start, number_end, options \\ [])
to_ratio_string(number, options \\ [])

Formats a number as a rational fraction string.

to_ratio_string!(number, options \\ [])

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

to_string(number, options \\ [])

Formats a number as a localized string.

to_string!(number, options \\ [])

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

## Functions

# parse(string, options \\ [])

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(list, options \\ [])

Resolves currencies from strings within a list.

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

# resolve_currency(string, options \\ [])

Resolves a currency from a string.

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

# resolve_per(string, options \\ [])

Resolves percent or permille from a string.

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

# resolve_pers(list, options \\ [])

Resolves percent and permille symbols from strings within a list.

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

# scan(string, options \\ [])

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(number, options \\ [])

    @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(number, options \\ [])

    @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(number, options \\ [])

    @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(range, options)

    @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 `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(number_start, number_end, options \\ [])

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

# to_range_string!(range, options)

    @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!(number_start, number_end, options \\ [])

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

# to_ratio_string(number, options \\ [])

    @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!(number, options \\ [])

    @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(number, options \\ [])

    @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 `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`. Any RBNF rule name atom supported by the locale is also accepted (e.g., `:spellout_cardinal`, `:spellout_ordinal`, `:digits_ordinal`, `:roman_upper`). The atoms `:spellout` and `:ordinal` resolve to the best available spellout or ordinal rule for the locale. See `Localize.Number.Rbnf.rule_names_for_locale/1` to discover the rule names supported by a locale.

- `: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.

- `:minimum_significant_digits` is an integer in `1..21` specifying the minimum number of significant digits the formatted output should retain. When set, significant-digit precision overrides the format pattern's fractional-digit settings. Defaults to the value derived from the format pattern's `@@##` notation, or `nil` (no significant-digit constraint).

- `:maximum_significant_digits` is an integer in `1..21` specifying the maximum number of significant digits to display. Values are rounded to fit using the configured `:rounding_mode`. Pairs with `:minimum_significant_digits`; when only one is set the other defaults to the corresponding ECMA-402 boundary (`1` for minimum, `21` for maximum).

- `: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!(number, options \\ [])

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