# `Localize.Number.Symbol`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/number/symbol.ex#L1)

Functions to manage the number symbol definitions for a locale
and number system.

Number symbols define the characters used for decimal separators,
grouping separators, percent signs, and other formatting elements.
Each locale may define symbols for one or more number systems
(e.g., `:latn`, `:arab`, `:thai`).

Symbol data is retrieved at runtime from locale data via the
configured locale provider.

# `t`

```elixir
@type t() :: %Localize.Number.Symbol{
  approximately_sign: String.t(),
  currency_decimal: String.t() | nil,
  currency_group: String.t() | nil,
  decimal: String.t() | map(),
  exponential: String.t(),
  group: String.t() | map(),
  infinity: String.t(),
  list: String.t(),
  minus_sign: String.t(),
  nan: String.t(),
  per_mille: String.t(),
  percent_sign: String.t(),
  plus_sign: String.t(),
  superscripting_exponent: String.t(),
  time_separator: String.t()
}
```

# `for_currency`

```elixir
@spec for_currency(t(), Localize.Currency.t()) :: t()
```

Returns the symbols to format an amount of a currency with.

Some locales separate a currency amount differently from a plain number.
CLDR gives these locales a `currencyDecimal` or a `currencyGroup` symbol,
which this function puts in place of the `:decimal` and `:group` symbols. A
currency with a decimal separator of its own, such as the Cape Verdean
escudo in `pt-CV`, takes that one instead.

`Localize.Number.to_string/2` formats with these symbols and
`Localize.Number.Parser.parse/2` reads with them, so a currency amount
parses back to the number it was formatted from.

### Arguments

* `symbols` is a `t:Localize.Number.Symbol.t/0` struct.

* `currency` is a `t:Localize.Currency.t/0` struct.

### Returns

* A `t:Localize.Number.Symbol.t/0` struct.

### Examples

    iex> {:ok, symbols} = Localize.Number.Symbol.number_symbols_for(:"fr-CH", :latn)
    iex> symbols.decimal
    %{standard: ","}
    iex> {:ok, currency} = Localize.Currency.currency_for_code(:CHF, locale: :"fr-CH")
    iex> Localize.Number.Symbol.for_currency(symbols, currency).decimal
    "."

# `number_symbols_for`

```elixir
@spec number_symbols_for(Localize.LanguageTag.t() | atom() | String.t()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Returns a map of `Localize.Number.Symbol.t()` structs of the
number symbols for each number system of a locale.

### Arguments

* `locale` is a locale identifier atom, string, or a
  `t:Localize.LanguageTag.t/0` struct.

### Returns

* `{:ok, symbols_map}` where `symbols_map` is a map of
  `%{system_name => Localize.Number.Symbol.t()}`.

* `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> {:ok, symbols} = Localize.Number.Symbol.number_symbols_for(:en)
    iex> symbols[:latn].decimal
    %{standard: "."}

# `number_symbols_for`

```elixir
@spec number_symbols_for(
  Localize.LanguageTag.t() | atom() | String.t(),
  atom() | String.t()
) ::
  {:ok, t()} | {:error, Exception.t()}
```

Returns the number symbols for a specific locale and number system.

### Arguments

* `locale` is a locale identifier atom, string, or a
  `t:Localize.LanguageTag.t/0` struct.

* `number_system` is a number system name atom or string
  (e.g., `:latn`, `:arab`).

### Returns

* `{:ok, Localize.Number.Symbol.t()}` with the symbols for the
  requested number system.

* `{:error, exception}` if the locale data cannot be loaded or
  no symbols exist for the number system.

When the requested number system has no symbol data of its own in
the locale, the locale's `latn` symbols stand in, as CLDR's root
aliases every numbering system's symbols to `latn`. The exceptions
are `arab` and `arabext`, whose root symbols are not in the CLDR JSON;
for those the symbols of the locale's default number system stand in.
This is what makes a `-u-nu-` override such as `en-u-nu-thai`
formattable.

### Examples

    iex> {:ok, symbols} = Localize.Number.Symbol.number_symbols_for(:en, :latn)
    iex> symbols.percent_sign
    "%"
    iex> symbols.group
    %{standard: ","}

---

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