Cldr Numbers v0.3.1 Cldr.Number.Format View Source

Functions to manage the collection of number patterns defined in Cldr.

Number patterns affect how numbers are interpreted in a localized context. Here are some examples, based on the French locale. The “.” shows where the decimal point should go. The “,” shows where the thousands separator should go. A “0” indicates zero-padding: if the number is too short, a zero (in the locale’s numeric set) will go there. A “#” indicates no padding: if the number is too short, nothing goes there. A “¤” shows where the currency sign will go. The following illustrates the effects of different patterns for the French locale, with the number “1234.567”. Notice how the pattern characters ‘,’ and ‘.’ are replaced by the characters appropriate for the locale.

Number Pattern Examples

PatternCurrencyText
#,##0.##n/a1 234,57
#,##0.###n/a1 234,567
###0.#####n/a1234,567
###0.0000#n/a1234,5670
00000.0000n/a01234,5670
#,##0.00 ¤EUR1 234,57 €

The number of # placeholder characters before the decimal do not matter, since no limit is placed on the maximum number of digits. There should, however, be at least one zero some place in the pattern. In currency formats, the number of digits after the decimal also do not matter, since the information in the supplemental data (see Supplemental Currency Data) is used to override the number of decimal places — and the rounding — according to the currency that is being formatted. That can be seen in the above chart, with the difference between Yen and Euro formatting.

Details of the number formats are described in the Unicode documentation

Link to this section Summary

Functions

The decimal formats defined for a given locale or for a given locale and number system

Returns the list of decimal formats in the configured locales including the list of locales configured for precompilation in config.exs

Returns the list of decimal formats for a configured locale

Returns the names of the number systems for the locale

Returns the number system types available for a locale

Return the predfined formats for a given locale and number_system

Return the predfined formats for a given locale and number_system or raises if either the locale or number_system is invalid

Returns the minium grouping digits for a locale

Returns the minium grouping digits for a locale or raises if there is an error

Link to this section Types

Link to this section Functions

Link to this function all_formats_for(locale \\ Cldr.get_current_locale()) View Source
all_formats_for(Cldr.LanguageTag.t()) :: Map.t()

The decimal formats defined for a given locale or for a given locale and number system.

Examples

Cldr.Number.Format.all_formats_for("en")
#=> %{latn: %Cldr.Number.Format{
  accounting: "¤#,##0.00;(¤#,##0.00)",
  currency: "¤#,##0.00",
  percent: "#,##0%",
  scientific: "#E0",
  standard: "#,##0.###",
  currency_short: [{"1000", [one: "¤0K", other: "¤0K"]},
   {"10000", [one: "¤00K", other: "¤00K"]},
   {"100000", [one: "¤000K", other: "¤000K"]},
   {"1000000", [one: "¤0M", other: "¤0M"]},
   {"10000000", [one: "¤00M", other: "¤00M"]},
   {"100000000", [one: "¤000M", other: "¤000M"]},
   {"1000000000", [one: "¤0B", other: "¤0B"]},
   {"10000000000", [one: "¤00B", other: "¤00B"]},
   {"100000000000", [one: "¤000B", other: "¤000B"]},
   {"1000000000000", [one: "¤0T", other: "¤0T"]},
   {"10000000000000", [one: "¤00T", other: "¤00T"]},
   {"100000000000000", [one: "¤000T", other: "¤000T"]}],
   ....
  }
Link to this function decimal_format_list() View Source
decimal_format_list() :: [format(), ...]

Returns the list of decimal formats in the configured locales including the list of locales configured for precompilation in config.exs.

This function exists to allow the decimal formatter to precompile all the known formats at compile time.

Example

Cldr.Number.Format.decimal_format_list ["#", "#,##,##0%",
#=> "#,##,##0.###", "#,##,##0.00¤", "#,##,##0.00¤;(#,##,##0.00¤)",
"#,##,##0 %", "#,##0%", "#,##0.###", "#,##0.00 ¤",
"#,##0.00 ¤;(#,##0.00 ¤)", "#,##0.00¤", "#,##0.00¤;(#,##0.00¤)",
"#,##0 %", "#0%", "#0.######", "#0.00 ¤", "#E0", "%#,##0", "% #,##0",
"0", "0.000000E+000", "0000 M ¤", "0000¤", "000G ¤", "000K ¤", "000M ¤",
"000T ¤", "000mM ¤", "000m ¤", "000 Bio'.' ¤", "000 Bln ¤", "000 Bn ¤",
"000 B ¤", "000 E ¤", "000 K ¤", "000 MRD ¤", "000 Md ¤", "000 Mio'.' ¤",
"000 Mio ¤", "000 Mld ¤", "000 Mln ¤", "000 Mn ¤", "000 Mrd'.' ¤",
"000 Mrd ¤", "000 Mr ¤", "000 M ¤", "000 NT ¤", "000 N ¤", "000 Tn ¤",
"000 Tr ¤", ...]
Link to this function decimal_format_list_for(locale \\ Cldr.get_current_locale()) View Source
decimal_format_list_for(Cldr.LanguageTag.t()) :: [String.t(), ...]

Returns the list of decimal formats for a configured locale.

This function exists to allow the decimal formatter to precompile all the known formats at compile time. Its use is not otherwise recommended.

Example

iex> Cldr.Number.Format.decimal_format_list_for Cldr.Locale.new("en")
["#,##0%", "#,##0.###", "#E0", "0 billion", "0 million", "0 thousand",
 "0 trillion", "00 billion", "00 million", "00 thousand", "00 trillion",
 "000 billion", "000 million", "000 thousand", "000 trillion", "000B", "000K",
 "000M", "000T", "00B", "00K", "00M", "00T", "0B", "0K", "0M", "0T",
 "¤#,##0.00", "¤#,##0.00;(¤#,##0.00)", "¤000B", "¤000K", "¤000M",
 "¤000T", "¤00B", "¤00K", "¤00M", "¤00T", "¤0B", "¤0K", "¤0M", "¤0T"]
Link to this function decimal_format_styles_for(locale \\ Cldr.get_current_locale(), number_system \\ :default) View Source
decimal_format_styles_for(Cldr.LanguageTag.t(), binary() | atom()) :: [atom()]

Returns the decimal format styles that are supported by Cldr.Number.Formatter.Decimal.

  • locale is any locale configured in the system. See Cldr.known_locales/0

  • number_system which defaults to :default and is either:

    • an atom in which case it is interpreted as a number system type in the given locale. Typically this would be either :default or :native. See Cldr.Number.Format.format_types_for/1 for the number system types available for a given locale.

    • a binary in which case it is used to look up the number system directly (for exmple "latn" which is common for western european languages). See Cldr.Number.Format.formats_for/1 for the available formats for a locale.

Example

iex> Cldr.Number.Format.decimal_format_styles_for Cldr.Locale.new("en")
[:accounting, :currency, :currency_long, :percent,
 :scientific, :standard]
Link to this function format_styles_for(locale \\ Cldr.get_current_locale(), number_system \\ :default) View Source
format_styles_for(Cldr.LanguageTag.t(), atom() | String.t()) :: [atom(), ...]

Returns the format styles available for a locale.

  • locale is any locale configured in the system. See Cldr.known_locales/0

  • number_system which defaults to :default and is either:

    • an atom in which case it is interpreted as a number system type in the given locale. Typically this would be either :default or :native. See Cldr.Number.Format.format_types_for/1 for the number system types available for a given locale.

    • a binary in which case it is used to look up the number system directly (for exmple "latn" which is common for western european languages). See Cldr.Number.Format.formats_for/1 for the available formats for a locale.

Format styles standardise the access to a format defined for a common use. These types are :standard, :currency, :accounting, :scientific and :percent, :currency_short, :decimal_short, :decimal_long.

These types can be used when formatting a number for output. For example Cldr.Number.to_string(123.456, format: :percent).

Example

iex> Cldr.Number.Format.format_styles_for(Cldr.Locale.new("en"))
[:accounting, :currency, :currency_long, :currency_short,
:decimal_long, :decimal_short, :percent, :scientific, :standard]
Link to this function format_system_names_for(locale \\ Cldr.get_current_locale()) View Source
format_system_names_for(Cldr.LanguageTag.t()) :: [String.t(), ...]

Returns the names of the number systems for the locale.

Examples

iex> Cldr.Number.Format.format_system_names_for(Cldr.Locale.new("th"))
{:ok, [:latn, :thai]}

iex> Cldr.Number.Format.format_system_names_for(Cldr.Locale.new("pl"))
{:ok, [:latn]}
Link to this function format_system_types_for(locale \\ Cldr.get_current_locale()) View Source
format_system_types_for(Cldr.LanguageTag.t()) :: [atom(), ...]

Returns the number system types available for a locale

A number system type is an identifier that categorises number systems that comprise a site of digits or rules for transliterating or translating digits and a number system name for determining plural rules and format masks.

If that all sounds a bit complicated then the default number system type called :default is probably what you want nearly all the time.

Examples

iex> Cldr.Number.Format.format_system_types_for Cldr.Locale.new("pl")
{:ok, [:default, :native]}

iex> Cldr.Number.Format.format_system_types_for Cldr.Locale.new("ru")
{:ok, [:default, :native]}

iex> Cldr.Number.Format.format_system_types_for Cldr.Locale.new("th")
{:ok, [:default, :native]}
Link to this function formats_for(locale \\ Cldr.get_current_locale(), number_system \\ :default) View Source
formats_for(Cldr.LanguageTag.t(), atom() | String.t()) :: Map.t()

Return the predfined formats for a given locale and number_system.

  • locale is any locale configured in the system. See Cldr.known_locales/0

  • number_system is either:

    • an atom in which case it is interpreted as a number system type in the given locale. Typically this would be either :default or :native. See Cldr.Number.Format.format_types_for/1 for the number system types available for a given locale.

    • a binary in which case it is used to look up the number system directly (for exmple "latn" which is common for western european languages). See Cldr.Number.Format.formats_for/1 for the available formats for a locale.

Example

Cldr.Number.Format.formats_for "fr", :native
#=> %Cldr.Number.Format{
  accounting: "#,##0.00 ¤;(#,##0.00 ¤)",
  currency: "#,##0.00 ¤",
  percent: "#,##0 %",
  scientific: "#E0",
  standard: "#,##0.###"
  currency_short: [{"1000", [one: "0 k ¤", other: "0 k ¤"]},
   {"10000", [one: "00 k ¤", other: "00 k ¤"]},
   {"100000", [one: "000 k ¤", other: "000 k ¤"]},
   {"1000000", [one: "0 M ¤", other: "0 M ¤"]},
   {"10000000", [one: "00 M ¤", other: "00 M ¤"]},
   {"100000000", [one: "000 M ¤", other: "000 M ¤"]},
   {"1000000000", [one: "0 Md ¤", other: "0 Md ¤"]},
   {"10000000000", [one: "00 Md ¤", other: "00 Md ¤"]},
   {"100000000000", [one: "000 Md ¤", other: "000 Md ¤"]},
   {"1000000000000", [one: "0 Bn ¤", other: "0 Bn ¤"]},
   {"10000000000000", [one: "00 Bn ¤", other: "00 Bn ¤"]},
   {"100000000000000", [one: "000 Bn ¤", other: "000 Bn ¤"]}],
   ...
  }
Link to this function formats_for!(locale \\ Cldr.get_current_locale(), number_system \\ :default) View Source
formats_for!(Cldr.LanguageTag.t(), atom() | String.t()) ::
  Map.t() |
  Exception.t()

Return the predfined formats for a given locale and number_system or raises if either the locale or number_system is invalid.

Link to this function minimum_grouping_digits_for(locale \\ Cldr.get_current_locale()) View Source
minimum_grouping_digits_for(Cldr.LanguageTag.t()) :: non_neg_integer()

Returns the minium grouping digits for a locale.

Examples

iex> Cldr.Number.Format.minimum_grouping_digits_for(Cldr.Locale.new("en"))
1
Link to this function minimum_grouping_digits_for!(locale) View Source

Returns the minium grouping digits for a locale or raises if there is an error.

Examples

iex> Cldr.Number.Format.minimum_grouping_digits_for!(Cldr.Locale.new("en"))
1

Cldr.Number.Format.minimum_grouping_digits_for!(Cldr.Locale.new("end"))
** (Cldr.UnknownLocaleError) The locale "end" is not known
Link to this function short_format_styles_for(locale \\ Cldr.get_current_locale(), number_system \\ :default) View Source
short_format_styles_for(Cldr.LanguageTag.t(), binary() | atom()) :: [atom(), ...]

Returns the short formats available for a locale.

  • locale is any locale configured in the system. See Cldr.known_locales/0

  • number_system which defaults to :default and is either:

    • an atom in which case it is interpreted as a number system type in the given locale. Typically this would be either :default or :native. See Cldr.Number.Format.format_types_for/1 for the number system types available for a given locale.

    • a binary in which case it is used to look up the number system directly (for exmple "latn" which is common for western european languages). See Cldr.Number.Format.formats_for/1 for the available formats for a locale.

Example

iex> Cldr.Number.Format.short_format_styles_for(Cldr.Locale.new("he"))
[:currency_short, :decimal_long, :decimal_short]