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

Formats a number according to locale conventions.

Arguments

• number is an integer, float, or Decimal.

• options is a keyword list of options.

Options

• :locale is a locale identifier string or atom. The default is the current process locale.

• :style is :decimal, :currency, :percent, or :unit. The default is :decimal.

• :currency is a currency code atom (for example, :USD, :EUR). Required when :style is :currency.

• :unit is a unit identifier string (for example, "kilometer", "liter"). Required when :style is :unit.

• :unit_display is :long, :short, or :narrow. Controls how the unit is displayed. The default is :short.

• :notation is :standard or :compact. When :compact, uses abbreviated number formatting (for example, "1.2K"). The default is :standard.

• :compact_display is :short or :long. Only used when :notation is :compact. The default is :short.

• :minimum_fraction_digits is a non-negative integer.

• :maximum_fraction_digits is a non-negative integer.

• :rounding_mode is one of :down, :half_up, :half_even, :ceiling, :floor, :half_down, :up.

Returns

• {:ok, formatted_string} on success.

• {:error, reason} if options or input are invalid.

Examples

iex> Intl.NumberFormat.format(1234.5, locale: :en)
{:ok, "1,234.5"}

iex> Intl.NumberFormat.format(0.56, locale: :en, style: :percent)
{:ok, "56%"}

iex> Intl.NumberFormat.format(1234.5, locale: :en, style: :currency, currency: :USD)
{:ok, "$1,234.50"}

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

Formats a number, raising on error.

Same as format/2 but returns the string directly or raises.

Arguments

• number is an integer, float, or Decimal.

• options is a keyword list of options.

Returns

• A formatted string.

Examples

iex> Intl.NumberFormat.format!(1234.5, locale: :en)
"1,234.5"

@spec format_range(number(), number(), Keyword.t()) ::
  {:ok, String.t()} | {:error, term()}

Formats a range of numbers according to locale conventions.

Arguments

• number_start is the start of the range.

• number_end is the end of the range.

• options is a keyword list of options. Accepts the same options as format/2 (except :style must be :decimal or omitted).

Returns

• {:ok, formatted_string} on success.

• {:error, reason} if options or input are invalid.

Examples

iex> Intl.NumberFormat.format_range(100, 200, locale: :en)
{:ok, "100–200"}

@spec format_range!(number(), number(), Keyword.t()) :: String.t() | no_return()

Formats a range of numbers, raising on error.

Same as format_range/3 but returns the string directly or raises.

Arguments

• number_start is the start of the range.

• number_end is the end of the range.

• options is a keyword list of options.

Returns

• A formatted string.

Examples

iex> Intl.NumberFormat.format_range!(100, 200, locale: :en)
"100–200"