@spec format(number(), options_input()) ::
  {:ok, String.t()} | {:error, format_error()}

Formats a number.

Accepts any numeric type (integer, float, or decimal-like struct that implements the required protocol). Returns {:ok, String.t()} or an error tuple when the input or options are invalid.

Examples

iex> Icu.Number.format(-123.45)
{:ok, "-123.450"}

iex> Icu.Number.format(42, sign_display: :always)
{:ok, "+42.000"}

iex> Icu.Number.format(194_438, notation: :compact)
{:ok, "194K"}

iex> Icu.Number.format(0.5, style: :percent)
{:ok, "50%"}

@spec format!(number(), options_input()) :: String.t()

Formats a number and raises on error.

Examples

iex> Icu.Number.format!(42, sign_display: :always)
"+42.000"

@spec format_compact(number(), options_input()) ::
  {:ok, compact_result()} | {:error, format_error()}

Formats a number in compact notation, returning both the string and the exact numeric value it represents.

Always uses notation: :compact (any :notation in options is ignored). Accepts the same inputs as format/2 (integers, floats, Decimals, including fractional values); :compact_display, :rounding_mode, :maximum_fraction_digits and :minimum_fraction_digits are the relevant knobs. When no fraction option is given, precision defaults to 1–2 significant digits of the abbreviated significand (6718 → "6.7K", 15400 → "15K"); :maximum_fraction_digits overrides that (15400 → "15.4K" at 1 digit), honouring :rounding_mode.

:displayed_value is a Decimal giving the exact numeric the abbreviation denotes. Compare it against the input to detect when the display understates the value (e.g. to append a localised "+"):

iex> {:ok, %{formatted: formatted, displayed_value: displayed}} =
...>   Icu.Number.format_compact(6_718, locale: "en", rounding_mode: :trunc)
iex> formatted
"6.7K"
iex> Decimal.compare(displayed, 6_718)
:lt

For a non-negative input, truncation never overstates the magnitude, so Decimal.compare(displayed_value, input) is :lt or :eq under rounding_mode: :trunc. (For a negative input, toward-zero truncation moves the value up instead.)

Examples

iex> {:ok, result} = Icu.Number.format_compact(194_438, locale: "en", rounding_mode: :trunc)
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"194K", "194000"}

iex> {:ok, result} = Icu.Number.format_compact(780, locale: "en")
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"780", "780"}

iex> # rounding_mode is directional only; trunc keeps the default precision
iex> {:ok, result} = Icu.Number.format_compact(6_718, locale: "en", rounding_mode: :trunc)
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"6.7K", "6700"}

iex> # for a badge-style whole-unit floor, ask for 0 fraction digits explicitly
iex> {:ok, result} =
...>   Icu.Number.format_compact(6_718,
...>     locale: "en",
...>     maximum_fraction_digits: 0,
...>     rounding_mode: :trunc
...>   )
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"6K", "6000"}

iex> # maximum_fraction_digits sets the abbreviated significand precision;
iex> # trunc floors it (1199 -> "1.1K", never "1.2K")
iex> {:ok, result} =
...>   Icu.Number.format_compact(1_199,
...>     locale: "en",
...>     maximum_fraction_digits: 1,
...>     rounding_mode: :trunc
...>   )
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"1.1K", "1100"}

iex> # fractional inputs are accepted; the Decimal denotes the string exactly
iex> {:ok, result} = Icu.Number.format_compact(5.5, locale: "en")
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"5.5", "5.5"}

@spec format_compact!(number(), options_input()) :: compact_result()

Formats a number in compact notation and raises on error.

Examples

iex> result = Icu.Number.format_compact!(194_438, locale: "en", rounding_mode: :trunc)
iex> {result.formatted, Decimal.to_string(result.displayed_value)}
{"194K", "194000"}

@spec format_to_parts(number(), options_input()) ::
  {:ok, [map()]} | {:error, format_error()}

Formats a number to parts using an existing formatter.

Returns tagged pieces (integer, decimal separator, fraction, etc.) so callers can add markup around specific components.

Examples

iex> {:ok, parts} = Icu.Number.format_to_parts(123.5)
iex> Enum.map(parts, & &1.part_type)
[:integer, :decimal, :fraction]

@spec format_to_parts!(number(), options_input()) :: [map()]

Formats a number to parts and raises on error.

Examples

iex> parts = Icu.Number.format_to_parts!(123.5)
iex> Enum.count(parts)
3