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

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, "๑,๒๓๔.๕"}

@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, :currency, or :percent; :unit ranges are not supported).

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"