View Source Cldr.Number.Format (Cldr Numbers v2.32.0)
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
| Pattern | Currency | Text |
|---|---|---|
| #,##0.## | n/a | 1 234,57 |
| #,##0.### | n/a | 1 234,567 |
| ###0.##### | n/a | 1234,567 |
| ###0.0000# | n/a | 1234,5670 |
| 00000.0000 | n/a | 01234,5670 |
| #,##0.00 ¤ | EUR | 1 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
Summary
Functions
Returns the decimal formats defined for a given locale.
Returns the decimal formats defined for a given locale.
Returns the currency space 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 decimal format styles that are supported by
Cldr.Number.Formatter.Decimal.
Returns the default grouping for a locale.
Returns the default grouping for a locale or raises if there is an error.
Returns the format styles available for a 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 minimum grouping digits for a locale.
Returns the minimum grouping digits for a locale or raises if there is an error.
Returns the short formats available for a locale.
Types
@type format() :: String.t()
Functions
@spec all_formats_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: {:ok, map()} | {:error, {module(), String.t()}}
Returns the decimal formats defined for a given locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
{:ok, map_of_formats_by_number_system}or{:error, {exception, reason}}.
Examples
Cldr.Number.Format.all_formats_for("en", MyApp.Cldr)
#=> {:ok, %{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"]}],
....
}}Returns the decimal formats defined for a given locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
a list of decimal formats or
raises an exception
See Cldr.Number.Format.all_formats_for/2 for further information.
currency_spacing(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec currency_spacing( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.Number.System.system_name(), Cldr.backend() ) :: map() | {:error, {module(), String.t()}}
Returns the currency space for a given locale and number system.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
- A map defining how spacing between a currency symbol and its number format should be applied.
Example
iex> Cldr.Number.Format.currency_spacing(:en, :latn, MyApp.Cldr)
%{
before_currency: %{
insert_between: " ",
surrounding_match: "[[:digit:]]",
currency_match: "[[:^S:]&[:^Z:]]"
},
after_currency: %{
insert_between: " ",
surrounding_match: "[[:digit:]]",
currency_match: "[[:^S:]&[:^Z:]]"
}
}@spec decimal_format_list(Cldr.backend()) :: [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.
Arguments
backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
[decimal_formats_as_strings].
##@ Example
=> Cldr.Number.Format.decimal_format_list(MyApp.Cldr)
["#", "#,##,##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 ¤", ...]decimal_format_list_for(locale, backend \\ Cldr.default_backend!())
View Source@spec decimal_format_list_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: {:ok, [String.t()]} | {:error, {module(), String.t()}}
Returns the list of decimal formats for a configured locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
This function exists to allow the decimal formatter to precompile all the known formats at compile time. Its use is not otherwise recommended.
Returns
{:ok, list_of_decimal_formats_as_strings}or{:error, {exception, reason}}.
Example
iex> Cldr.Number.Format.decimal_format_list_for("en", MyApp.Cldr)
{:ok, ["#,##0%", "#,##0.###", "#,##0.00", "#,##0.00;(#,##0.00)","#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",
"¤ #,##0.00", "¤ #,##0.00;(¤ #,##0.00)", "¤ 000B", "¤ 000K", "¤ 000M",
"¤ 000T", "¤ 00B", "¤ 00K", "¤ 00M", "¤ 00T", "¤ 0B", "¤ 0K", "¤ 0M", "¤ 0T"]}decimal_format_styles_for(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec decimal_format_styles_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.Number.System.system_name(), Cldr.backend() ) :: {:ok, [atom()]} | {:error, {module(), String.t()}}
Returns the decimal format styles that are supported by
Cldr.Number.Formatter.Decimal.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Example
iex> {:ok, styles} = Cldr.Number.Format.decimal_format_styles_for("en", :latn, MyApp.Cldr)
iex> Enum.sort(styles)
[
:accounting,
:accounting_alpha_next_to_number,
:accounting_no_symbol,
:currency,
:currency_alpha_next_to_number,
:currency_long,
:currency_no_symbol,
:percent,
:scientific,
:standard
]@spec default_grouping_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: {:ok, non_neg_integer()} | {:error, {module(), String.t()}}
Returns the default grouping for a locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/0.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
{:ok, minumum_digits}or{:error, {exception, message}}
Examples
iex> Cldr.Number.Format.default_grouping_for("en", MyApp.Cldr)
{:ok, %{fraction: %{first: 0, rest: 0}, integer: %{first: 3, rest: 3}}}@spec default_grouping_for!( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: map() | no_return()
Returns the default grouping for a locale or raises if there is an error.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
- default grouping definition as a map.
Examples
iex> Cldr.Number.Format.default_grouping_for!("en", MyApp.Cldr)
%{fraction: %{first: 0, rest: 0}, integer: %{first: 3, rest: 3}}
Cldr.Number.Format.default_grouping_for!(:invalid)
** (Cldr.UnknownLocaleError) The locale :invalid is invalidformat_styles_for(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec format_styles_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.Number.System.system_name(), Cldr.backend() ) :: {:ok, [atom()]} | {:error, {module(), String.t()}}
Returns the format styles available for a locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
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).
Returns
[format_styles]or{:error, {exception, reason}}.
Example
iex> {:ok, format_styles} = Cldr.Number.Format.format_styles_for("en", :latn, MyApp.Cldr)
iex> Enum.sort(format_styles)
[
:accounting,
:accounting_alpha_next_to_number,
:accounting_no_symbol,
:currency,
:currency_alpha_next_to_number,
:currency_long,
:currency_no_symbol,
:currency_short,
:decimal_long,
:decimal_short,
:percent,
:scientific,
:standard
]format_system_names_for(locale, backend \\ Cldr.default_backend!())
View Source@spec format_system_names_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: {:ok, [atom()]} | {:error, {module(), String.t()}}
Returns the names of the number systems for the locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Examples
iex> Cldr.Number.Format.format_system_names_for("th", MyApp.Cldr)
{:ok, [:latn, :thai]}
iex> Cldr.Number.Format.format_system_names_for("pl", MyApp.Cldr)
{:ok, [:latn]}format_system_types_for(locale, backend \\ Cldr.default_backend!())
View Source@spec format_system_types_for( Cldr.Locale.locale_name() | Cldr.LanguageTag.t(), Cldr.backend() ) :: {:ok, Keyword.t()} | {:error, {module(), String.t()}}
Returns the number system types available for a locale
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
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("pl", MyApp.Cldr)
{:ok, [:default, :native]}
iex> Cldr.Number.Format.format_system_types_for("ru", MyApp.Cldr)
{:ok, [:default, :native]}
iex> Cldr.Number.Format.format_system_types_for("th", MyApp.Cldr)
{:ok, [:default, :native]}formats_for(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec formats_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), atom() | String.t(), Cldr.backend() ) :: {:ok, map()} | {:error, {module(), String.t()}}
Return the predfined formats for a given locale and number_system.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2orCldr.Number.System.number_system_names_for/2.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
{:ok, Cldr.Number.Format struct}or{:error, {exception, reason}}.
Example
Cldr.Number.Format.formats_for "fr", :native, MyApp.Cldr
#=> {:ok, %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 ¤"]}],
...
}}formats_for!(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec formats_for!( Cldr.LanguageTag.t(), Cldr.Number.System.system_name(), Cldr.backend() ) :: map() | no_return()
Return the predfined formats for a given locale and number_system or raises
if either the locale or number_system is invalid.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
Cldr.Number.Format structorraises an exception.
minimum_grouping_digits_for(locale, backend \\ Cldr.default_backend!())
View Source@spec minimum_grouping_digits_for(Cldr.LanguageTag.t(), Cldr.backend()) :: {:ok, non_neg_integer()} | {:error, {module(), String.t()}}
Returns the minimum grouping digits for a locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/0.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
{:ok, minumum_digits}or{:error, {exception, message}}
Examples
iex> Cldr.Number.Format.minimum_grouping_digits_for("en", MyApp.Cldr)
{:ok, 1}minimum_grouping_digits_for!(locale, backend \\ Cldr.default_backend!())
View SourceReturns the minimum grouping digits for a locale or raises if there is an error.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Returns
- the number of grouping digits as an integer
Examples
iex> Cldr.Number.Format.minimum_grouping_digits_for!("en", MyApp.Cldr)
1
Cldr.Number.Format.minimum_grouping_digits_for!(:invalid)
** (Cldr.UnknownLocaleError) The locale :invalid is invalidshort_format_styles_for(locale, number_system, backend \\ Cldr.default_backend!())
View Source@spec short_format_styles_for( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), binary() | atom(), Cldr.backend() ) :: {:ok, [atom()]} | {:error, {module(), String.t()}}
Returns the short formats available for a locale.
Arguments
localeis any valid locale name returned byCldr.known_locale_names/1or aCldr.LanguageTagstruct returned byCldr.Locale.new!/2. The default isCldr.get_locale/1.number_systemis any valid number system or number system type returned byCldr.Number.System.number_systems_for/2.backendis anyCldrbackend. That is, any module that containsuse Cldr. The default isCldr.default_backend!/0which will raiee an exception if not default backend is configured.
Example
iex> {:ok, short_format_styles} = Cldr.Number.Format.short_format_styles_for("he", :latn, MyApp.Cldr)
iex> Enum.sort(short_format_styles)
[:currency_short, :decimal_long, :decimal_short]