Cldr.Number.System (Cldr Numbers v2.17.0) View Source

Functions to manage number systems which describe the numbering characteristics for a locale.

A number system defines the digits (if they exist in this number system) or or rules (if the number system does not have decimal digits).

The system name is also used as a key to define the separators that are used when formatting a number is this number_system. See Cldr.Number.Symbol.number_symbols_for/2.

Link to this section Summary

Functions

Return the default number system type name.

Generate a transliteration map between two character classes

Returns {:ok, digits} for a number system, or an {:error, message} if the number system is not known.

Returns digits for a number system, or raises an exception if the number system is not know.

Returns the actual number system from a number system type.

Returns the number system from a language tag or locale name.

Returns the names of the number systems available for a locale or an {:error, message} tuple if the locale is not known.

Returns the names of the number systems available for a locale or an {:error, message} tuple if the locale is not known.

Return a map of all CLDR number systems and definitions.

Returns the number systems available for a locale or {:error, message} if the locale is not known.

Returns the number systems available for a locale or raises if the locale is not known.

Returns locale and number systems that have the same digits and separators as the supplied one.

Returns a number system name for a given locale and number system reference.

Returns a number system name for a given locale and number system reference and raises if the number system is not available for the given locale.

Number systems that have their own digit characters defined.

Converts a number into the representation of a non-latin number system.

Converts a number into the representation of a non-latin number system. Returns a converted string or raises on error.

Returns an error tuple for an number system unknown to a given locale.

Link to this section Types

Specs

system_name() :: atom()

Specs

types() :: :default | :native | :traditional | :finance

Link to this section Functions

Link to this function

default_number_system_type()

View Source

Return the default number system type name.

Currently this is :default. Note that this is not the number system itself but the type of the number system. It can be used to find the default number system for a given locale with number_systems_for(locale)[default_number_system()].

Example

iex> Cldr.Number.System.default_number_system_type
:default
Link to this function

generate_transliteration_map(from, to)

View Source

Generate a transliteration map between two character classes

Arguments

  • from is any String.t() intended to represent the digits of a number system but thats not a requirement.

  • to is any String.t() that is the same length as from intended to represent the digits of a number system.

Returns

  • A map where the keys are the graphemes in from and the values are the graphemes in to or

  • {:error, {exception, reason}}

Examples

iex> Cldr.Number.System.generate_transliteration_map "0123456789", "9876543210"
%{
  "0" => "9",
  "1" => "8",
  "2" => "7",
  "3" => "6",
  "4" => "5",
  "5" => "4",
  "6" => "3",
  "7" => "2",
  "8" => "1",
  "9" => "0"
}

iex> Cldr.Number.System.generate_transliteration_map "0123456789", "987654321"
{:error,
 {ArgumentError, "\"0123456789\" and \"987654321\" aren't the same length"}}
Link to this function

known_number_system_types(backend)

View Source

See Cldr.known_number_system_types/1.

See Cldr.known_number_systems/0.

Link to this function

number_system_digits(system_name)

View Source

Specs

number_system_digits(system_name()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns {:ok, digits} for a number system, or an {:error, message} if the number system is not known.

Arguments

Returns

  • {:ok, string_of_digits} or

  • {:error, {exception, reason}}

Examples

iex> Cldr.Number.System.number_system_digits(:latn)
{:ok, "0123456789"}

iex> Cldr.Number.System.number_system_digits(:nope)
{:error, {Cldr.UnknownNumberSystemError, "The number system :nope is not known or does not have digits"}}
Link to this function

number_system_digits!(system_name)

View Source

Specs

number_system_digits!(system_name()) :: String.t() | no_return()

Returns digits for a number system, or raises an exception if the number system is not know.

Arguments

Returns

  • A string of the number systems digits or

  • raises an exception

Examples

iex> Cldr.Number.System.number_system_digits! :latn
"0123456789"

Cldr.Number.System.number_system_digits! :nope
** (Cldr.UnknownNumberSystemError) The number system :nope is not known or does not have digits
Link to this function

number_system_for(locale, system_name, backend)

View Source

Specs

number_system_for(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  system_name(),
  Cldr.backend()
) :: {:ok, map()} | {:error, {module(), String.t()}}

Returns the actual number system from a number system type.

Arguments

Returns

  • {:ok, number_system_map} or

  • {:error, {exception, reason}}

Notes

This function will decode a number system type into the actual number system. If the number system provided can't be decoded it is returned as is.

Examples

iex> Cldr.Number.System.number_system_for "th", :latn, TestBackend.Cldr
{:ok, %{digits: "0123456789", type: :numeric}}

iex> Cldr.Number.System.number_system_for "en", :default, TestBackend.Cldr
{:ok, %{digits: "0123456789", type: :numeric}}

iex> Cldr.Number.System.number_system_for "he", :traditional, TestBackend.Cldr
{:ok, %{rules: "hebrew", type: :algorithmic}}

iex> Cldr.Number.System.number_system_for "en", :finance, TestBackend.Cldr
{
  :error,
  {Cldr.UnknownNumberSystemError,
    "The number system :finance is unknown for the locale named \"en\". Valid number systems are %{default: :latn, native: :latn}"}
}

iex> Cldr.Number.System.number_system_for "en", :native, TestBackend.Cldr
{:ok, %{digits: "0123456789", type: :numeric}}
Link to this function

number_system_from_locale(locale_name)

View Source
Link to this function

number_system_from_locale(locale, backend)

View Source

Specs

number_system_from_locale(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  Cldr.backend()
) :: system_name()

Returns the number system from a language tag or locale name.

Arguments

Returns

  • A number system name as an atom

Examples

iex> Cldr.Number.System.number_system_from_locale "en-US-u-nu-thai"
:thai

iex> Cldr.Number.System.number_system_from_locale "en-US"
:latn
Link to this function

number_system_names_for(locale, backend)

View Source

Specs

number_system_names_for(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend()
) :: {:ok, [atom()]} | {:error, {module(), String.t()}}

Returns the names of the number systems available for a locale or an {:error, message} tuple if the locale is not known.

Arguments

Examples

iex> Cldr.Number.System.number_system_names_for("en", TestBackend.Cldr)
{:ok, [:latn]}

iex> Cldr.Number.System.number_system_names_for("th", TestBackend.Cldr)
{:ok, [:latn, :thai]}

iex> Cldr.Number.System.number_system_names_for("he", TestBackend.Cldr)
{:ok, [:latn, :hebr]}

iex> Cldr.Number.System.number_system_names_for("zz", TestBackend.Cldr)
{:error, {Cldr.UnknownLocaleError, "The locale \"zz\" is not known."}}
Link to this function

number_system_names_for!(locale, backend)

View Source

Specs

number_system_names_for!(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend()
) :: [system_name()] | no_return()

Returns the names of the number systems available for a locale or an {:error, message} tuple if the locale is not known.

Arguments

Examples

iex> Cldr.Number.System.number_system_names_for!("en", TestBackend.Cldr)
[:latn]

iex> Cldr.Number.System.number_system_names_for!("th", TestBackend.Cldr)
[:latn, :thai]

iex> Cldr.Number.System.number_system_names_for!("he", TestBackend.Cldr)
[:latn, :hebr]

Specs

number_systems() :: map()

Return a map of all CLDR number systems and definitions.

Example

iex> Cldr.Number.System.number_systems |> Enum.count
85
Link to this function

number_systems_for(locale, backend)

View Source

Specs

number_systems_for(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend()
) :: {:ok, map()} | {:error, {module(), String.t()}}

Returns the number systems available for a locale or {:error, message} if the locale is not known.

Arguments

Examples

iex> Cldr.Number.System.number_systems_for "en"
{:ok, %{default: :latn, native: :latn}}

iex> Cldr.Number.System.number_systems_for "th"
{:ok, %{default: :latn, native: :thai}}

iex> Cldr.Number.System.number_systems_for "zz", TestBackend.Cldr
{:error, {Cldr.UnknownLocaleError, "The locale \"zz\" is not known."}}
Link to this function

number_systems_for!(locale, backend)

View Source

Specs

number_systems_for!(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend()
) :: map() | no_return()

Returns the number systems available for a locale or raises if the locale is not known.

Arguments

Examples

iex> Cldr.Number.System.number_systems_for! "en"
%{default: :latn, native: :latn}

iex> Cldr.Number.System.number_systems_for! "th", TestBackend.Cldr
%{default: :latn, native: :thai}
Link to this function

number_systems_like(locale, number_system, backend)

View Source

Specs

number_systems_like(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  system_name(),
  Cldr.backend()
) :: {:ok, list()} | {:error, {module(), String.t()}}

Returns locale and number systems that have the same digits and separators as the supplied one.

Arguments

Returns

Notes

Transliterating between locale & number systems is expensive. To avoid unncessary transliteration we look for locale and number systems that have the same digits and separators. Typically we are comparing to locale "en" and number system "latn" since this is what the number formatting routines use as placeholders.

Examples

Link to this function

system_name_from(system_name, locale, backend)

View Source

Specs

system_name_from(
  system_name(),
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend()
) :: {:ok, atom()} | {:error, {module(), String.t()}}

Returns a number system name for a given locale and number system reference.

Arguments

Notes

Number systems can be references in one of two ways:

  • As a number system type such as :default, :native, :traditional and :finance. This allows references to a number system for a locale in a consistent fashion for a given use

  • WIth the number system name directly, such as :latn, :arab or any of the other 70 or so

This function dereferences the supplied system_name and returns the actual system name.

Examples

ex> Cldr.Number.System.system_name_from(:default, "en", TestBackend.Cldr)
{:ok, :latn}

iex> Cldr.Number.System.system_name_from("latn", "en", TestBackend.Cldr)
{:ok, :latn}

iex> Cldr.Number.System.system_name_from(:native, "en", TestBackend.Cldr)
{:ok, :latn}

iex> Cldr.Number.System.system_name_from(:nope, "en", TestBackend.Cldr)
{
  :error,
  {Cldr.UnknownNumberSystemError, "The number system :nope is unknown"}
}

Note that return value is not guaranteed to be a valid number system for the given locale as demonstrated in the third example.

Link to this function

system_name_from!(system_name, locale, backend)

View Source

Specs

Returns a number system name for a given locale and number system reference and raises if the number system is not available for the given locale.

Arguments

Examples

iex> Cldr.Number.System.system_name_from!(:default, "en", TestBackend.Cldr)
:latn

iex> Cldr.Number.System.system_name_from!("latn", "en", TestBackend.Cldr)
:latn

iex> Cldr.Number.System.system_name_from!(:traditional, "he", TestBackend.Cldr)
:hebr

Number systems that have their own digit characters defined.

Link to this function

to_system(number, system_name, backend)

View Source

Specs

to_system(Cldr.Math.number_or_decimal(), atom(), Cldr.backend()) ::
  {:ok, binary()} | {:error, {module(), String.t()}}

Converts a number into the representation of a non-latin number system.

This function converts numbers to a known number system only, it does not provide number formatting.

Arguments

Returns

  • {:ok, string_of_digits} or

  • {:error, {exception, reason}}

Notes

There are two types of number systems in CLDR:

  • :numeric in which the number system defines a direct mapping between the latin digits 0..9 into a the number system equivalent. In this case, to_system/3 invokes Cldr.Number.Transliterate.transliterate_digits/3 for the given number.

  • :algorithmic in which the number system does not have the same structure as the :latn number system and therefore the conversion is done algorithmically. For CLDR the algorithm is implemented through Cldr.Rbnf rulesets. These rulesets are considered by CLDR to be less rigorous than the :numeric number systems and caution and testing for a specific use case is recommended.

Examples

iex> Cldr.Number.System.to_system 123456, :hebr, TestBackend.Cldr
{:ok, "קכ״ג׳תנ״ו"}

iex> Cldr.Number.System.to_system 123, :hans, TestBackend.Cldr
{:ok, "一百二十三"}

iex> Cldr.Number.System.to_system 123, :hant, TestBackend.Cldr
{:ok, "一百二十三"}

iex> Cldr.Number.System.to_system 123, :hansfin, TestBackend.Cldr
{:ok, "壹佰贰拾叁"}
Link to this function

to_system!(number, system_name, backend)

View Source

Specs

Converts a number into the representation of a non-latin number system. Returns a converted string or raises on error.

Arguments

Returns

  • string_of_digits or

  • raises an exception

See Cldr.Number.System.to_system/3 for further information.

Examples

iex> Cldr.Number.System.to_system! 123, :hans, TestBackend.Cldr
"一百二十三"

iex> Cldr.Number.System.to_system! 123, :hant, TestBackend.Cldr
"一百二十三"

iex> Cldr.Number.System.to_system! 123, :hansfin, TestBackend.Cldr
"壹佰贰拾叁"
Link to this function

unknown_number_system_for_locale_error(number_system, locale, valid_number_systems)

View Source

Returns an error tuple for an number system unknown to a given locale.

Arguements