View Source Cldr.Number.Format.Meta (Cldr Numbers v2.32.0)
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"]
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/4
.[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 that 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
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.