View Source Cldr.Number.Format.Meta (Cldr Numbers v2.31.3)
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:
:positivewhich is a keyword list for formatting a number >= zero:negativewhich 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"]insertsstringinto the format without any processing[currency: 1..4]inserts a localised currency symbol of the giventype. A:currencymust be provided as an option toCldr.Number.Formatter.Decimal.to_string/4.[pad: "char"]inserts the correct number ofchars to pad the number format to the width specified by:padding_lengthin the%Meta{}struct. The:padcan be anywhere in the format list but it is most typically inserted before or after the:formatkeyword. The assumption is that thecharis 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:
- The standard currency symbol like
$,¥or€ - The ISO currency code (like
USDandJPY) - The localised and pluralised currency display name like "Australian dollar" or "Australian dollars"
- The narrow currency symbol if defined for a locale
Summary
Functions
Returns a new number formatting metadata struct.
Set the number of exponent digits to format.
Set whether to add the sign of the exponent to the format.
Set the metadata format for the positive and negative number format.
Set the minimum, and optionally maximum, fractional digits to format.
Sets the number of digits in a group or optionally the first group and subsequent groups for the fractional part of a number.
Set the minimum, and optionally maximum, integer digits to format.
Sets the number of digits in a group or optionally the first group and subsequent groups for the integer part of a number.
Sets the multiplier for the number.
Set the padding character to be used when padding the formatted number.
Set the increment to which the number should be rounded.
Set the number of scientific digits to which the number should be rounded.
Set the minimum, and optionally maximum, significant digits to format.
Types
@type t() :: %Cldr.Number.Format.Meta{ currency: term(), exponent_digits: term(), exponent_sign: term(), format: term(), fractional_digits: term(), grouping: term(), integer_digits: term(), multiplier: term(), number: term(), padding_char: term(), padding_length: term(), round_nearest: term(), scientific_rounding: term(), significant_digits: term() }
Metadata type that drives how to format a number
Functions
@spec new() :: t()
Returns a new number formatting metadata struct.
@spec put_exponent_digits(t(), non_neg_integer()) :: t()
Set the number of exponent digits to format.
Set whether to add the sign of the exponent to the format.
Set the metadata format for the positive and negative number format.
Note that this is the parsed format as a simple keyword list, not a binary representation.
Its up to each formatting engine to transform its input
into this form. See Cldr.Number.Format.Meta module
documentation for the available keywords.
@spec put_fraction_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, fractional digits to format.
@spec put_fraction_grouping(t(), non_neg_integer()) :: t()
@spec put_fraction_grouping(t(), non_neg_integer(), non_neg_integer()) :: t()
Sets the number of digits in a group or optionally the first group and subsequent groups for the fractional part of a number.
The grouping character is defined by the locale
defined for the current process or supplied
as the :locale option to to_string/3.
@spec put_integer_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, integer digits to format.
@spec put_integer_grouping(t(), non_neg_integer()) :: t()
@spec put_integer_grouping(t(), non_neg_integer(), non_neg_integer()) :: t()
Sets the number of digits in a group or optionally the first group and subsequent groups for the integer part of a number.
The grouping character is defined by the locale
defined for the current process or supplied
as the :locale option to to_string/3.
@spec put_multiplier(t(), non_neg_integer()) :: t()
Sets the multiplier for the number.
Before formatting, the number is multiplied by this amount. This is useful when formatting as a percent or permille.
Set the padding character to be used when padding the formatted number.
@spec put_padding_length(t(), non_neg_integer()) :: t()
@spec put_round_nearest_digits(t(), non_neg_integer()) :: t()
Set the increment to which the number should be rounded.
@spec put_scientific_rounding_digits(t(), non_neg_integer()) :: t()
Set the number of scientific digits to which the number should be rounded.
@spec put_significant_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, significant digits to format.