Money.Input.Currency (Money.Input v0.1.0)

Currency + locale display data for money input components.

Given a locale and a currency, returns the data a UI needs to render a currency-aware input correctly: the locale's number-system separators, the currency symbol resolved per CLDR rules, the symbol's position relative to the digits (read from the locale's currency format pattern, not guessed), and the currency's fractional-digit precision.

All locale lookups go through Localize.validate_locale/1; the resulting Localize.LanguageTag.t/0's :cldr_locale_id is the canonical id we report back. Number system resolution goes through Localize.Number.System.number_system_from_locale/1 so Arabic-Indic, Persian, and other non-Latin digit systems are handled correctly (no assumption of :latn).

Summary

Types

t()

Locale + currency display data resolved by currency_for_locale/2.

Functions

currency_for_locale(locale \\ nil, options \\ [])

Resolves currency and locale display data for the given locale (and optional currency).

Types

t()

@type t() :: %Money.Input.Currency{
  currency: Localize.Currency.t() | nil,
  decimal: String.t(),
  group: String.t(),
  iso_digits: non_neg_integer() | nil,
  language_tag: Localize.LanguageTag.t(),
  locale: atom(),
  minus_sign: String.t(),
  number_system: atom(),
  symbol: String.t() | nil,
  symbol_position: :prefix | :suffix | nil
}

Locale + currency display data resolved by currency_for_locale/2.

:locale — the canonical CLDR locale id (atom).
:language_tag — the full Localize.LanguageTag.t/0 for callers needing access to extensions, regions, scripts, etc.
:number_system — the active number system (:latn, :arab, :arabext, …).
:decimal — the locale's decimal separator character.
:group — the locale's grouping separator character.
:minus_sign — the locale's minus sign character.
:currency — a Localize.Currency.t/0 for the requested currency, or nil when no currency was supplied.
:symbol — the currency symbol resolved per Localize.Currency.symbol/2 (kind selected via the :symbol_kind option). nil when no currency was supplied.
:symbol_position — :prefix or :suffix, derived from the locale's CLDR currency format pattern. nil when no currency was supplied.
:iso_digits — the currency's ISO 4217 fractional digit count (USD: 2, JPY: 0, BHD: 3). nil when no currency.

Functions

currency_for_locale(locale \\ nil, options \\ [])

@spec currency_for_locale(
  Localize.LanguageTag.t() | atom() | String.t() | nil,
  Keyword.t()
) ::
  {:ok, t()} | {:error, Exception.t()}

Resolves currency and locale display data for the given locale (and optional currency).

Arguments

locale is a locale identifier (atom, string, or Localize.LanguageTag.t/0). Defaults to Localize.get_locale/0.
options is a keyword list of options.

Options

:currency — an ISO 4217 currency code (atom or string). When given, currency-specific fields (:currency, :symbol, :symbol_position, :iso_digits) are populated. When omitted, those fields are nil.
:symbol_kind — which currency-marker variant to surface as :symbol. One of :standard (default), :symbol, :narrow, :iso, :none. Forwarded to Localize.Currency.symbol/2.

Returns

{:ok, t()} on success.
{:error, Exception.t()} when the locale can't be parsed, the number system can't be resolved, number symbols are missing for the locale, or the currency code is unknown.

Examples

iex> {:ok, info} = Money.Input.Currency.currency_for_locale(:en, currency: :USD)
iex> {info.decimal, info.group, info.symbol, info.symbol_position, info.iso_digits}
{".", ",", "$", :prefix, 2}

iex> {:ok, info} = Money.Input.Currency.currency_for_locale(:de, currency: :EUR)
iex> {info.decimal, info.group, info.symbol, info.symbol_position}
{",", ".", "€", :suffix}

iex> {:ok, info} = Money.Input.Currency.currency_for_locale(:ja, currency: :JPY)
iex> info.iso_digits
0