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}.

Resolves currencies from strings within a list.

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

Resolves a currency from a string.

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

Resolves percent or permille from a string.

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

Resolves percent and permille symbols from strings within a list.

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

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.

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

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

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

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

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

@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⁠½"}

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

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

• :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%"}

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