Icu.Experimental.Currency (icu v0.4.0)

Locale-aware currency formatting.

format/2 delegates to the ICU4X currency formatter using the application locale (:icu, :default_locale). Use the convenience API for one-off conversions or build a persistent formatter via Icu.Currency.Formatter.new/1 when you need to reuse the same configuration.

Examples

iex> Icu.Experimental.Currency.format(1234.56, currency: "USD")
{:ok, "$1,234.56"}

iex> Icu.Experimental.Currency.format(1234.56, currency: "EUR", locale: "de-DE")
{:ok, "1.234,56 €"}

Options

:currency – required – ISO 4217 currency code (e.g. "USD", "EUR", "JPY").
:width – display width (:short, :narrow, :long). Defaults to :short.
:locale – override the locale for this invocation.

Summary

Types

currency()

ISO 4217 currency code.

currency_digits()

Controls which fraction digits/rounding increment to use.

format_error()

formatter()

Opaque reference to an ICU4X currency formatter.

fractions()

options()

Map form of the supported options.

options_input()

options_list()

Keyword form of the supported options.

round_options()

Options for round/2.

round_options_list()

rounding_mode()

Any Decimal.Context rounding mode.

width()

Controls the display width of the currency.

Functions

currency_fractions(currency)

Returns currency fraction data for a given ISO 4217 currency code.

format(number, options)

Formats a number as currency.

format!(number, options)

Formats a number as currency and raises on error.

round(number, options)

Rounds a number according to CLDR currency fraction rules.

round!(number, options)

Like round/2, but raises on error. See round/2 for details.

Types

currency()

@type currency() :: String.t()

ISO 4217 currency code.

currency_digits()

@type currency_digits() :: :iso | :cash | non_neg_integer()

Controls which fraction digits/rounding increment to use.

:iso (default) — standard digits / rounding from CLDR fractions data
:cash — cash_digits / cash_rounding from CLDR fractions data
non-negative integer — round to exactly N digits, no increment rounding

format_error()

@type format_error() ::
  :invalid_formatter
  | :invalid_number
  | :invalid_locale
  | :invalid_options
  | :invalid_currency
  | {:missing_option, :currency}

formatter()

@type formatter() :: Icu.Experimental.Currency.Formatter.t()

Opaque reference to an ICU4X currency formatter.

fractions()

@type fractions() :: %{
  digits: non_neg_integer(),
  rounding: non_neg_integer(),
  cash_digits: non_neg_integer(),
  cash_rounding: non_neg_integer()
}

options()

@type options() :: %{
  :currency => currency(),
  optional(:width) => width(),
  optional(:locale) => Icu.LanguageTag.t() | String.t() | nil,
  optional(:currency_digits) => currency_digits(),
  optional(:rounding_mode) => rounding_mode()
}

Map form of the supported options.

options_input()

@type options_input() :: options() | options_list()

options_list()

@type options_list() :: [
  currency: currency(),
  width: width(),
  locale: Icu.LanguageTag.t() | String.t() | nil,
  currency_digits: currency_digits(),
  rounding_mode: rounding_mode()
]

Keyword form of the supported options.

round_options()

@type round_options() :: %{
  :currency => currency(),
  optional(:currency_digits) => currency_digits(),
  optional(:rounding_mode) => rounding_mode()
}

Options for round/2.

round_options_list()

@type round_options_list() :: [
  currency: currency(),
  currency_digits: currency_digits(),
  rounding_mode: rounding_mode()
]

rounding_mode()

@type rounding_mode() ::
  :down | :half_up | :half_even | :ceiling | :floor | :half_down | :up

Any Decimal.Context rounding mode.

width()

@type width() :: :short | :narrow | :long

Controls the display width of the currency.

Functions

currency_fractions(currency)

@spec currency_fractions(currency()) ::
  {:ok, fractions()} | {:error, :invalid_currency}

Returns currency fraction data for a given ISO 4217 currency code.

format(number, options)

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

Formats a number as currency.

Requires the :currency option with a valid ISO 4217 currency code. Returns {:ok, String.t()} or an error tuple when the input or options are invalid.

Examples

iex> Icu.Experimental.Currency.format(12345.67, currency: "USD")
{:ok, "$12,345.67"}

iex> Icu.Experimental.Currency.format(12345.67, currency: "USD", width: :long)
{:ok, "12,345.67 US dollars"}

format!(number, options)

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

Formats a number as currency and raises on error.

Examples

iex> Icu.Experimental.Currency.format!(12345.67, currency: "USD")
"$12,345.67"

round(number, options)

@spec round(number() | Decimal.t(), round_options() | round_options_list()) ::
  {:ok, Decimal.t()} | {:error, term()}

Rounds a number according to CLDR currency fraction rules.

Experimental

This function is experimental and implements limited CLDR currency rounding functionality. The API and behaviour may change in future releases.

Options

:currency — required — ISO 4217 currency code.
:currency_digits — :iso (default), :cash, or a non-negative integer.
:rounding_mode — any Decimal.Context rounding mode, default :half_even.

Examples

iex> Icu.Experimental.Currency.round(123.456, currency: "USD")
{:ok, Decimal.new("123.46")}

iex> Icu.Experimental.Currency.round(123.456, currency: "JPY")
{:ok, Decimal.new("123")}

iex> Icu.Experimental.Currency.round(123.73, currency: "CHF", currency_digits: :cash)
{:ok, Decimal.new("123.75")}

round!(number, options)

@spec round!(number() | Decimal.t(), round_options() | round_options_list()) ::
  Decimal.t()

Like round/2, but raises on error. See round/2 for details.