@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, :scientific, :engineering, 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. Compact currency formatting always uses the short form since CLDR defines no long compact currency format.

• :currency_display is :symbol, :narrow_symbol, :code, or :name. Controls how the currency is presented. The default is :symbol.

• :currency_sign is :standard or :accounting. When :accounting, negative currency amounts render in the locale's accounting format (for example, "($1,234.50)"). The default is :standard.

• :use_grouping is :always, :auto, :min2, true, or false. :min2 groups only when there are at least two digits in a group; false disables grouping. The default is :auto.

• :sign_display is :auto, :always, :except_zero, :negative, or :never. Controls when the sign is displayed. The default is :auto.

• :minimum_integer_digits is an integer in 1..21. The integer part is zero-padded to at least this many digits.

• :minimum_fraction_digits is a non-negative integer.

• :maximum_fraction_digits is a non-negative integer.

• :minimum_significant_digits is an integer in 1..21.

• :maximum_significant_digits is an integer in 1..21. When set, significant-digit precision overrides fraction-digit precision.

• :numbering_system is a CLDR numbering system name (for example, :latn, :thai). Any valid CLDR numbering system may be used with any locale, including algorithmic systems such as :roman.

• :rounding_increment is a positive integer. The formatted value is rounded to the nearest multiple of this increment.

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

• :rounding_priority is :auto, :more_precision, or :less_precision. Resolves conflicts when both fraction-digit and significant-digit options are given. The default is :auto (significant digits win).

• :trailing_zero_display is :auto or :strip_if_integer. When :strip_if_integer, fraction digits are dropped if the rounded value is an integer. The default is :auto.

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

iex> Intl.NumberFormat.format(1234.5, locale: :en, notation: :scientific)
{:ok, "1.2345E3"}

iex> Intl.NumberFormat.format(1234, locale: :en, style: :currency, currency: :USD, notation: :compact)
{:ok, "$1.2K"}

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

iex> Intl.NumberFormat.format(1234567, locale: :en, use_grouping: false)
{:ok, "1234567"}

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

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

iex> Intl.NumberFormat.format(1234.5, locale: :en, numbering_system: :thai)
{:ok, "๑,๒๓๔.๕"}

iex> Intl.NumberFormat.format(5, locale: :en, minimum_integer_digits: 3)
{:ok, "005"}

iex> Intl.NumberFormat.format(1000, locale: :en, minimum_fraction_digits: 2, trailing_zero_display: :strip_if_integer)
{:ok, "1,000"}

@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, including style: :unit with :unit and :unit_display (the unit pattern is applied once to the range, "2–5 kilometers").

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

iex> Intl.NumberFormat.format_range(100, 200, locale: :en, style: :currency, currency: :USD)
{:ok, "$100.00–$200.00"}

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

@spec format_range_to_parts(number(), number(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t(), source: atom()}]} | {:error, term()}

Formats a range of numbers into a list of typed parts.

Modelled on the JS Intl.NumberFormat.formatRangeToParts(). In addition to :type and :value, each part carries a :source key: :start_range, :end_range, or :shared.

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, including style: :unit (the unit pattern text carries source :shared).

Returns

• {:ok, parts} where parts is a list of %{type: atom, value: String.t(), source: atom} maps.

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

Examples

iex> Intl.NumberFormat.format_range_to_parts(3, 5, locale: :en)
{:ok, [
  %{type: :integer, value: "3", source: :start_range},
  %{type: :literal, value: "–", source: :shared},
  %{type: :integer, value: "5", source: :end_range}
]}

@spec format_range_to_parts!(number(), number(), Keyword.t()) ::
  [%{type: atom(), value: String.t(), source: atom()}] | no_return()

Formats a range of numbers into typed parts, raising on error.

Same as format_range_to_parts/3 but returns the parts 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 list of %{type: atom, value: String.t(), source: atom} maps.

Examples

iex> Intl.NumberFormat.format_range_to_parts!(3, 5, locale: :en) |> length()
3

@spec format_to_parts(number() | Decimal.t(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, term()}

Formats a number into a list of typed parts.

Modelled on the JS Intl.NumberFormat.formatToParts(). Each part is a map with a :type and a :value key, allowing custom rendering of individual segments (for example, styling the currency symbol differently from the digits).

Arguments

• number is an integer, float, or Decimal.

• options is a keyword list of options. Accepts the same options as format/2, including style: :unit (the unit text is a :unit part) and currency_display: :name (the currency name is a :currency part).

Returns

• {:ok, parts} on success, where parts is a list of %{type: atom, value: String.t()} maps. Part types include :integer, :group, :decimal, :fraction, :currency, :percent_sign, :minus_sign, :plus_sign, :compact, :exponent_separator, :exponent_integer, and :literal.

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

Examples

iex> Intl.NumberFormat.format_to_parts(-1234.5, locale: :en)
{:ok, [
  %{type: :minus_sign, value: "-"},
  %{type: :integer, value: "1"},
  %{type: :group, value: ","},
  %{type: :integer, value: "234"},
  %{type: :decimal, value: "."},
  %{type: :fraction, value: "5"}
]}

iex> Intl.NumberFormat.format_to_parts(1_500_000, locale: :en, notation: :compact, compact_display: :long)
{:ok, [
  %{type: :integer, value: "1"},
  %{type: :decimal, value: "."},
  %{type: :fraction, value: "5"},
  %{type: :literal, value: " "},
  %{type: :compact, value: "million"}
]}

@spec format_to_parts!(number() | Decimal.t(), Keyword.t()) ::
  [%{type: atom(), value: String.t()}] | no_return()

Formats a number into a list of typed parts, raising on error.

Same as format_to_parts/2 but returns the parts directly or raises.

Arguments

• number is an integer, float, or Decimal.

• options is a keyword list of options.

Returns

• A list of %{type: atom, value: String.t()} maps.

Examples

iex> Intl.NumberFormat.format_to_parts!(56, locale: :en)
[%{type: :integer, value: "56"}]