Describes the metadata that drives number formatting and provides functions to update the struct.

Format definition

The :format is a keyword list that with two elements:

• :positive which is a keyword list for formatting a number >= zero

• :negative which is a keyword list for formatting negative number

There are two formats because we can format in an accounting style (that is, numbers surrounded by ()) or any other arbitrary style. Typically the format for a negative number is the same as that for a positive number with a prepended minus sign.

Localisation of number formatting

Number formatting is always localised to either the currency processes locale or a locale provided as an option to Cldr.Number.to_string/3.

The metadata is independent of the localisation process. Signs (+/-), grouping (,), decimal markers (.) and exponent signs are all localised when the number is formatted.

Formatting directives

The formats - positive and negative - are defined in the metadata struct, as a keyword list of keywords and values.

The simplest formatting list might be:

[format: _]`

The :format keyword indicates that this is where the formatting number will be substituted into the format pattern.

Another example would be for formatting a negative number:

[minus: _, format: _]

which will format with a localised minus sign followed by the formatted number. Note that the keyword value for :minus and :format are ignored.

List of formatting keywords

The following is the full list of formatting keywords which can be used to format a number. A _ in the keyword format is used to denote :dont_care.

• [format: _] inserts the formatted number exclusive of any sign

• [minus: _] inserts a localised minus sign

• [plus: _] inserts a localised plus sign

• [percent: _] inserts a localised percent sign

• [permille: _] inserts a localised permille sign

• [literal: "string"] inserts string into the format without any processing

• [currency: 1..4] inserts a localised currency symbol of the given type. A :currency must be provided as an option to Cldr.Number.Formatter.Decimal.to_string/4.

• [pad: "char"] inserts the correct number of chars to pad the number format to the width specified by :padding_length in the %Meta{} struct. The :pad can be anywhere in the format list but it is most typically inserted before or after the :format keyword. The assumption is that the char is a single binary character but this is not checked.

Currency symbol formatting

Currency are localised and have four ways of being presented. The different types are defined in the [currency: type] keyword where type is an integer in the range 1..4 These types will insert into the final format:

1. The standard currency symbol like $,¥ or €
2. The ISO currency code (like USD and JPY)
3. The localised and pluralised currency display name like "Australian dollar" or "Australian dollars"
4. The narrow currency symbol if defined for a locale