Localize.Number.Symbol (Localize v1.4.0)

Copy Markdown View Source

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.

Summary

Types

t()

Functions

for_currency(symbols, currency)

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

number_symbols_for(locale)

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

number_symbols_for(locale, number_system)

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

Types

t()

@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()
}

Functions

for_currency(symbols, currency)

@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

Returns

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(locale)

@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

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(locale, number_system)

@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 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: ","}