Cldr.Number.Format.Meta (Cldr Numbers v2.16.0) View Source
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 negtive 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"]
insertsstring
into the format without any processing[currency: 1..4]
inserts a localised currency symbol of the giventype
. A:currency
must be provided as an option toCldr.Number.Formatter.Decimal.to_string/3
.[pad: "char"]
inserts the correct number ofchar
s 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 tha thechar
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:
- The standard currency symbol like
$
,¥
or€
- The ISO currency code (like
USD
andJPY
) - The localised and pluralised currency display name like "Australian dollar" or "Australian dollars"
- The narrow currency symbol if defined for a locale
Link to this section 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.
Link to this section Types
Specs
t() :: %Cldr.Number.Format.Meta{ 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
Link to this section Functions
Specs
new() :: t()
Returns a new number formatting metadata struct.
Specs
put_exponent_digits(t(), non_neg_integer()) :: t()
Set the number of exponent digits to format.
Specs
Set whether to add the sign of the exponent to the format.
Specs
Specs
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.
Specs
put_fraction_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, fractional digits to format.
Specs
put_fraction_grouping(t(), non_neg_integer()) :: t()
Specs
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
.
Specs
put_integer_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, integer digits to format.
Specs
put_integer_grouping(t(), non_neg_integer()) :: t()
Specs
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
.
Specs
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.
Specs
Set the padding character to be used when padding the formatted number.
Specs
put_padding_length(t(), non_neg_integer()) :: t()
Specs
put_round_nearest_digits(t(), non_neg_integer()) :: t()
Set the increment to which the number should be rounded.
Specs
put_scientific_rounding_digits(t(), non_neg_integer()) :: t()
Set the number of scientific digits to which the number should be rounded.
Specs
put_significant_digits(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the minimum, and optionally maximum, significant digits to format.