Search documentation of bb

# BB.Cldr.Number.System (bb v0.8.0)

View Source

# Summary

## Functions

number_system_for(locale, system_name)

Returns the actual number system from a number system type.

number_system_from_locale(locale)

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

number_system_names_for(locale)

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

number_system_names_for!(locale)
number_system_types_for(locale)
number_systems_for(locale)

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

number_systems_for!(locale)
number_systems_like(locale, number_system)
system_name_from(system_name, locale)

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

to_system(number, system)

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

to_system!(number, system_name)

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

# Functions

# number_system_for(locale, system_name)

    @spec number_system_for(
      Cldr.Locale.locale_reference(),
      Cldr.Number.System.system_name()
    ) ::
      {:ok, [atom()]} | {:error, {module(), String.t()}}

Returns the actual number system from a number system type.

- `locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`

- `system_name` is any number system name returned by `Cldr.known_number_systems/0` or a number system type returned by `Cldr.known_number_system_types/0`

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> BB.Cldr.Number.System.number_system_for "th", :latn
    {:ok, %{digits: "0123456789", type: :numeric}}

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

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

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

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

# number_system_from_locale(locale)

    @spec number_system_from_locale(Cldr.Locale.locale_reference()) ::
      Cldr.Number.System.system_name() | {:error, {module(), String.t()}}

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

## Arguments

- `locale` is any language tag returned be `Cldr.Locale.new/2` or a locale name in the list returned by `Cldr.known_locale_names/1`

## Returns

- A number system name as an atom

## Examples

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

    iex> BB.Cldr.Number.System.number_system_from_locale "en-US"
    :latn

# number_system_names_for(locale)

    @spec number_system_names_for(Cldr.Locale.locale_reference()) ::
      {:ok, [atom()]} | {:error, {module(), String.t()}}

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

- `locale` is any valid locale name returned by `BB.Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct returned by `BB.Cldr.Locale.new!/1`

## Examples

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

    iex> BB.Cldr.Number.System.number_system_names_for "zz"
    {:error, {Cldr.InvalidLanguageError, "The language \"zz\" is invalid"}}

# number_system_names_for!(locale)

# number_system_types_for(locale)

# number_systems_for(locale)

    @spec number_systems_for(Cldr.Locale.locale_reference()) ::
      {:ok, map()} | {:error, {module(), String.t()}}

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

- `locale` is any valid locale name returned by `BB.Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct returned by `BB.Cldr.Locale.new!/1`

## Examples

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

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

    iex> BB.Cldr.Number.System.number_systems_for "zz"
    {:error, {Cldr.InvalidLanguageError, "The language \"zz\" is invalid"}}

# number_systems_for!(locale)

# number_systems_like(locale, number_system)

    @spec number_systems_like(
      Cldr.Locale.locale_reference(),
      Cldr.Number.System.system_name()
    ) ::
      {:ok, list()} | {:error, {module(), String.t()}}

# system_name_from(system_name, locale)

    @spec system_name_from(
      Cldr.Number.System.system_name(),
      Cldr.Locale.locale_reference()
    ) ::
      {:ok, Cldr.Number.System.system_name()} | {:error, {module(), String.t()}}

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

- `system_name` is any number system name returned by `BB.Cldr.known_number_systems/0` or a number system type returned by `BB.Cldr.known_number_system_types/0`

- `locale` is any valid locale name returned by `BB.Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct returned by `BB.Cldr.Locale.new!/1`

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> BB.Cldr.Number.System.system_name_from(:default, "en")
    {:ok, :latn}

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

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

    iex> BB.Cldr.Number.System.system_name_from(:nope, "en")
    {
      :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.

# to_system(number, system)

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.

- `number` is a `float`, `integer` or `Decimal`

- `system_name` is any number system name returned by `Cldr.known_number_systems/0` or a number system type returned by `Cldr.known_number_system_types/0`

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/2` 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> BB.Cldr.Number.System.to_system 123456, :hebr
    {:ok, "קכ״ג׳תנ״ו"}

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

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

    iex> BB.Cldr.Number.System.to_system 123, :hansfin
    {:ok, "壹佰贰拾叁"}

# to_system!(number, system_name)

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

- `number` is a `float`, `integer` or `Decimal`

- `system_name` is any number system name returned by `BB.Cldr.known_number_systems/0` or a number system type returned by `BB.Cldr.known_number_system_types/0`

See `BB.Cldr.Number.System.to_system/2` for further information.

## Examples

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

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

    iex> BB.Cldr.Number.System.to_system! 123, :hansfin
    "壹佰贰拾叁"