Packages
ex_cldr
0.0.14
2.47.5
2.47.4
2.47.3
2.47.2
2.47.1
2.47.0
2.46.0
2.45.2
2.45.1
2.45.0
2.44.1
2.44.0
2.43.2
2.43.1
2.43.0
2.42.0
2.41.1
2.41.0
2.40.4
2.40.3
2.40.2
2.40.1
2.40.0
2.39.2
2.39.1
2.39.0
2.38.1
2.38.0
2.37.5
2.37.4
2.37.3
retired
2.37.2
2.37.1
2.37.0
2.36.0
2.35.1
2.35.0
retired
2.34.2
2.34.1
2.34.0
2.33.2
2.33.1
2.33.1-rc.0
2.33.0
2.32.1
2.32.0
2.31.0
2.30.0
2.29.0
2.28.0
2.27.1
2.27.0
retired
2.26.3
2.26.2
2.26.1
2.26.0
2.25.0
2.24.2
2.24.1
2.24.0
2.24.0-rc.6
2.24.0-rc.5
2.24.0-rc.4
2.24.0-rc.3
2.24.0-rc.2
2.24.0-rc.1
2.24.0-rc.0
2.23.2
2.23.1
2.23.0
2.22.1
2.22.0
2.21.0
2.20.0
2.20.0-rc.3
2.20.0-rc.2
2.20.0-rc.1
2.20.0-rc.0
2.19.1
2.19.0
2.18.2
2.18.1
2.18.0
2.18.0-rc.0
2.17.2
2.17.1
2.17.0
2.16.2
2.16.1
2.16.1-rc.0
2.16.0
2.15.0
2.14.1
2.14.0
2.14.0-rc.0
2.13.0
2.12.1
2.12.0
2.11.1
2.11.0
2.10.2
2.10.1
2.10.0
retired
2.9.0
2.8.1
2.8.0
2.7.2
2.7.1
2.7.0
2.6.2
2.6.1
2.6.0
2.5.0
2.4.3
2.4.2
2.4.1
2.4.0
2.3.2
2.3.1
2.3.0
2.2.7
2.2.6
2.2.5
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.1.0
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
2.0.0-rc.3
retired
2.0.0-rc.2
retired
2.0.0-rc.1
retired
2.0.0-rc.0
retired
1.8.2
1.8.1
1.8.0
1.7.1
1.7.0
1.6.4
1.6.3
1.6.2
1.6.1
1.6.0
1.5.2
1.5.1
1.5.0
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
retired
1.4.0-rc.3
retired
1.4.0-rc.2
retired
1.4.0-rc.1
retired
1.4.0-rc.0
retired
1.3.2
1.3.1
1.3.0
1.2.0
1.1.0
1.0.0
1.0.0-rc.3
retired
1.0.0-rc.2
retired
1.0.0-rc.1
retired
1.0.0-rc.0
retired
0.13.1
0.13.0
0.12.2
retired
0.12.1
retired
0.12.0
retired
0.11.0
retired
0.10.0
retired
0.9.0
retired
0.8.3
retired
0.8.2
retired
0.8.1
retired
0.8.0
retired
0.7.0
retired
0.6.2
retired
0.6.1
retired
0.6.0
retired
0.5.2
retired
0.5.1
retired
0.5.0
retired
0.4.2
retired
0.4.1
retired
0.4.0
retired
0.3.0
retired
0.2.1
retired
0.2.0
retired
0.1.3
retired
0.1.2
retired
0.1.1
retired
0.1.0
retired
0.0.20
retired
0.0.19
retired
0.0.18
retired
0.0.17
retired
0.0.16
retired
0.0.15
retired
0.0.14
retired
0.0.13
retired
0.0.12
retired
0.0.11
retired
0.0.10
retired
0.0.8
retired
0.0.7
retired
0.0.6
retired
0.0.5
retired
0.0.4
retired
0.0.3
retired
Common Locale Data Repository (CLDR) functions for Elixir to localize and format numbers, dates, lists, messages, languages, territories and units with support for over 700 locales for internationalized (i18n) and localized (L10N) applications.
Retired package: Deprecated
Current section
Files
Jump to
Current section
Files
guides/3_number_formats.md
# Number and Currency formatting
CLDR defines many different ways to format a number for different uses and defines a set of formats categorised by common pupose to make it easier to express the same intent across many different locales that represent many different territories, cultures, number systems and scripts.
See `Cldr.Number` and `Cldr.Number.to_string/2`
## Public API
The primary api for number formatting is `Cldr.Number.to_string/2`. It provides the ability to format numbers in a standard way for configured locales. It also provides the means for format numbers as a currency, as a short form (like 1k instead of 1,000). Additionally it provides formats to spell a number in works, format it as roman numerals and output an ordinal number. Some examples illustrate:
iex> Cldr.Number.to_string 12345
"12,345"
iex> Cldr.Number.to_string 12345, locale: "fr"
"12 345"
iex> Cldr.Number.to_string 12345, locale: "fr", currency: "USD"
"12 345,00 $US"
iex(4)> Cldr.Number.to_string 12345, format: "#E0"
"1.2345E4"
iex> Cldr.Number.to_string 12345, format: :accounting, currency: "THB"
"THB12,345.00"
iex> Cldr.Number.to_string -12345, format: :accounting, currency: "THB"
"(THB12,345.00)"
iex> Cldr.Number.to_string 12345, format: :accounting, currency: "THB", locale: "th"
"THB12,345.00"
iex> Cldr.Number.to_string 12345, format: :accounting, currency: "THB", locale: "th", number_system: :native
"THB๑๒,๓๔๕.๐๐"
iex> Cldr.Number.to_string 1244.30, format: :long
"1 thousand"
iex> Cldr.Number.to_string 1244.30, format: :long, currency: "USD"
"1,244.30 US dollars"
iex> Cldr.Number.to_string 1244.30, format: :short
"1K"
iex> Cldr.Number.to_string 1244.30, format: :short, currency: "EUR"
"€1.24K"
iex> Cldr.Number.to_string 1234, format: :spellout
"one thousand two hundred thirty-four"
iex> Cldr.Number.to_string 1234, format: :spellout_verbose
"one thousand two hundred and thirty-four"
iex> Cldr.Number.to_string 123, format: :ordinal
"123rd"
iex(4)> Cldr.Number.to_string 123, format: :roman
"CXXIII"
## Formatting Styles
`Cldr` supports the styles of formatting defined by CLDR being:
* `standard` which formats a number if a decimal format commonly used in many locales.
* `currency` which formats a number according to the format or a particular currency adjusted for rounding, number of decimal digits after the fraction, whether the currency is accounting or cash rounded and using the appropriate locale-specific currency symbol.
* `accounting` which formats a positive number like `standard` but which usually wraps a negative number in `()`.
* `percent` which multiplies a number by 100 and includes a locale-specific percent symbol. Usually `%`.
* `permille` which multiples a number by 1,000 and includes a locale specific permille symbol. Usually `‰`.
* `scientific` which formats a number as a mantissa and base-10 exponent.
See `Cldr.Number.Formatter.Decimal`
## Short & Long Formats
`Cldr` also supports formats that minimise publishing space or which attempt to make large number more human-readable.
* `decimal_short` which presents number is a narrow space. For example, `1,000` would be formatted as `1k`.
* `decimal_long` which presents numbers in a sentence form adjusted for plurality and locale. For example, `1,0000` would be formatted as `1 thousand`. This is not the same as spelling out the number which is part of the Unicode CLDR Rules-Based Number Formatting. This capability is not yet available in `Cldr`
* `currency_short` which formats a number in a manner similar to `decimal_short` but includes the symbol currency.
* `currency_long` which formats a number in a manner similar to `decimal_long` but incudes the localised name of the current.
See `Cldr.Number.Formatter.Short` and `Cldr.Number.Formatter.Currency`.
## User-Specified Decimal Formats
User-defined decimal formats are also supported using the formats described by
[Unicode technical report TR35](http://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns).
The formats described therein are supported by `Cldr` with some minor omissions and variations. Some examples of number formats are:
| 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 |
| 00 | n/a | 12 |
| #,##0.00 ¤ | EUR | 1 234,57 € |
See `Cldr.Number` and `Cldr.Number.Formatter.Decimal`.
## Rule Based Number Formats
CLDR provides an additional mechanism for the formatting of numbers. The two primary purposes of such rules are to support formatting numbers:
* As words. For example, formatting 123 into "one hundred and twenty-three" for the "en" locale. The applicable format is `:spellout`
* As a year. In many languages the written form of a year is different to that used for an arbitrary number. For example, formatting 1989 would result in "nineteen eighty-nine". The applicable format is :spellout_year
* As an ordinal. For example, formatting 123 into "123rd". The applicable format type is `:ordinal`
* As Roman numerals. For example, formatting 123 into "CXXIII". The applicable formats are `:roman` or `:roman_lower`
There are also many additional methods more specialised to a specific locale that cater for languages with more complex gender and grammar requirements. Since these rules are specialised to a locale it is not possible to standarise the public API more than described in this section.
The full set of RBNF formats is accessable through the modules `Cldr.Rbnf.Ordinal`, `Cldr.Rbnf.Spellout` and `Cldr.Rbnf.NumberSystems`.
Each of these modules has a set of functions that are generated at compile time that implement the relevant RBNF rules. The available rules for a given locale can be retrieved by calling `Cldr.Rbnf.Spellout.rule_set(locale)` or the same function on the other modules. For example:
iex> Cldr.Rbnf.Ordinal.rule_sets "en"
[:digits_ordinal]
iex> Cldr.Rbnf.Spellout.rule_sets "fr"
[:spellout_ordinal_masculine_plural, :spellout_ordinal_masculine,
:spellout_ordinal_feminine_plural, :spellout_ordinal_feminine,
:spellout_numbering_year, :spellout_numbering, :spellout_cardinal_masculine,
:spellout_cardinal_feminine]
These rule-based formats are invoked directly on the required module passing the number and locale. For example:
iex> Cldr.Rbnf.Spellout.spellout_numbering_year 1989, "fr"
"dix-neuf-cent quatre-vingt-neuf"
iex> Cldr.Rbnf.Spellout.spellout_numbering_year 1989, "en"
"nineteen eighty-nine"
iex> Cldr.Rbnf.Ordinal.digits_ordinal 1989, "en"
"1,989th"
### RBNF Rules with Float numbers
RBNF is primarily oriented towards positive integral numbers. Whilst the standard caters for negative numbers and fractional numbers the implementation of the rules is incomplete. Use with care.