Cldr.Number.Format.Meta (Cldr Numbers v2.35.2)

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 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

Summary

Types

t()

Metadata type that drives how to format a number

Functions

new()

Returns a new number formatting metadata struct.

put_exponent_digits(meta, digits)

Set the number of exponent digits to format.

put_exponent_sign(meta, flag)

Set whether to add the sign of the exponent to the format.

put_format(meta, positive_format)
put_format(meta, positive_format, negative_format)

Set the metadata format for the positive and negative number format.

put_fraction_digits(meta, min, max \\ 0)

Set the minimum, and optionally maximum, fractional digits to format.

put_fraction_grouping(meta, all)
put_fraction_grouping(meta, first, rest)

Sets the number of digits in a group or optionally the first group and subsequent groups for the fractional part of a number.

put_integer_digits(meta, min, max \\ 0)

Set the minimum, and optionally maximum, integer digits to format.

put_integer_grouping(meta, all)
put_integer_grouping(meta, first, rest)

Sets the number of digits in a group or optionally the first group and subsequent groups for the integer part of a number.

put_multiplier(meta, multiplier)

Sets the multiplier for the number.

put_padding_char(meta, char)

Set the padding character to be used when padding the formatted number.

put_padding_length(meta, digits)
put_round_nearest_digits(meta, digits)

Set the increment to which the number should be rounded.

put_scientific_rounding_digits(meta, digits)

Set the number of scientific digits to which the number should be rounded.

put_significant_digits(meta, min, max \\ 0)

Set the minimum, and optionally maximum, significant digits to format.

Types

t()

@type t() :: %Cldr.Number.Format.Meta{
  currency: nil | Cldr.Currency.t(),
  exponent_digits: non_neg_integer(),
  exponent_sign: boolean(),
  format: [{:negative, [any(), ...]} | {:positive, [any(), ...]}, ...],
  fractional_digits: %{max: non_neg_integer(), min: non_neg_integer()},
  grouping: %{
    fraction: %{first: non_neg_integer(), rest: non_neg_integer()},
    integer: %{first: non_neg_integer(), rest: non_neg_integer()}
  },
  integer_digits: %{max: non_neg_integer(), min: non_neg_integer()},
  multiplier: non_neg_integer(),
  number: non_neg_integer(),
  padding_char: String.t(),
  padding_length: non_neg_integer(),
  round_nearest: non_neg_integer(),
  scientific_rounding: non_neg_integer(),
  significant_digits: %{max: non_neg_integer(), min: non_neg_integer()}
}

Metadata type that drives how to format a number

Functions

new()

@spec new() :: t()

Returns a new number formatting metadata struct.

put_exponent_digits(meta, digits)

@spec put_exponent_digits(t(), non_neg_integer()) :: t()

Set the number of exponent digits to format.

put_exponent_sign(meta, flag)

@spec put_exponent_sign(t(), boolean()) :: t()

Set whether to add the sign of the exponent to the format.

put_format(meta, positive_format)

@spec put_format(t(), Keyword.t()) :: t()

put_format(meta, positive_format, negative_format)

@spec put_format(t(), Keyword.t(), Keyword.t()) :: t()

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.

put_fraction_digits(meta, min, max \\ 0)

@spec put_fraction_digits(t(), non_neg_integer(), non_neg_integer()) :: t()

Set the minimum, and optionally maximum, fractional digits to format.

put_fraction_grouping(meta, all)

@spec put_fraction_grouping(t(), non_neg_integer()) :: t()

put_fraction_grouping(meta, first, rest)

@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.

put_integer_digits(meta, min, max \\ 0)

@spec put_integer_digits(t(), non_neg_integer(), non_neg_integer()) :: t()

Set the minimum, and optionally maximum, integer digits to format.

put_integer_grouping(meta, all)

@spec put_integer_grouping(t(), non_neg_integer()) :: t()

put_integer_grouping(meta, first, rest)

@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.

put_multiplier(meta, multiplier)

@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.

put_padding_char(meta, char)

@spec put_padding_char(t(), String.t()) :: t()

Set the padding character to be used when padding the formatted number.

put_padding_length(meta, digits)

@spec put_padding_length(t(), non_neg_integer()) :: t()

put_round_nearest_digits(meta, digits)

@spec put_round_nearest_digits(t(), non_neg_integer()) :: t()

Set the increment to which the number should be rounded.

put_scientific_rounding_digits(meta, digits)

@spec put_scientific_rounding_digits(t(), non_neg_integer()) :: t()

Set the number of scientific digits to which the number should be rounded.

put_significant_digits(meta, min, max \\ 0)

@spec put_significant_digits(t(), non_neg_integer(), non_neg_integer()) :: t()

Set the minimum, and optionally maximum, significant digits to format.