# `Money.Input.Currency`
[🔗](https://github.com/ex-money/money_input/blob/v0.3.3/lib/money/input/currency.ex#L1)

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 `t: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`).

# `t`

```elixir
@type t() :: %Money.Input.Currency{
  currency: Localize.Currency.t() | nil,
  decimal: String.t(),
  group: String.t(),
  grouping: %{first: non_neg_integer(), rest: non_neg_integer()},
  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 `t: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.

* `:grouping` — the integer digit grouping, as `%{first: 3,
  rest: 3}` (`1,234,567`) or `%{first: 3, rest: 2}` for the
  Indian system (`12,34,567`). It is read from the locale's
  currency pattern without a symbol, the one the amount is
  written with, which groups in threes in `en-IN`, `ta`, `mr`,
  `ml` and `or` though their other patterns are Indian.

* `:currency` — a `t:Localize.Currency.t/0` for the requested
  currency, or `nil` when no currency was supplied. A currency
  the locale does not list is read from the locale's parents
  and then the default locale, as `Money.to_string/2` writes it.

* `: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.

# `currency_for_locale`

```elixir
@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
  `t: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

    iex> {:ok, info} = Money.Input.Currency.currency_for_locale(:hi, currency: :INR)
    iex> info.grouping
    %{first: 3, rest: 2}

---

*Consult [api-reference.md](api-reference.md) for complete listing*
