Search documentation of Localize

# Localize.Number.Format (Localize v0.39.0)

Copy Markdown View Source

Functions to manage the collection of number format patterns defined in CLDR.

Number patterns affect how numbers are interpreted in a localized context. A format pattern such as `"#,##0.###"` defines the decimal and grouping separators, zero-padding, and digit positions. The actual separator characters are determined by the locale's number symbols.

Format data is retrieved at runtime from locale data via the configured locale provider.

## Summary

### Types

format()
t()

### Functions

all_formats_for(locale)

Returns all number formats defined for a locale, keyed by number system.

all_formats_for!(locale)

Same as `all_formats_for/1` but raises on error.

currency_spacing(locale, number_system \\ :default)

Returns the currency spacing rules for a locale and number system.

default_grouping_for(locale)

Returns the default grouping definition for a locale.

default_grouping_for!(locale)

Same as `default_grouping_for/1` but raises on error.

format_styles_for(locale, number_system \\ :default)

Returns the format styles available for a locale and number system.

format_system_names_for(locale)

Returns the number system names available for a locale.

format_system_types_for(locale)

Returns the number system types available for a locale.

formats_for(locale, number_system \\ :default)

Returns the format definitions for a given locale and number system.

formats_for!(locale, number_system \\ :default)

Same as `formats_for/2` but raises on error.

minimum_grouping_digits_for(locale)

Returns the minimum grouping digits for a locale.

minimum_grouping_digits_for!(locale)

Same as `minimum_grouping_digits_for/1` but raises on error.

misc_patterns_for(locale, number_system \\ :latn)

Returns the miscellaneous number patterns for a locale and number system.

short_format_styles()

Returns the short format style names.

short_format_styles_for(locale, number_system \\ :default)

Returns the short format styles available for a locale and number system.

## Types

# format()

    @type format() :: String.t()

# t()

    @type t() :: %Localize.Number.Format{
      accounting: term(),
      accounting_alpha_next_to_number: term(),
      accounting_no_symbol: term(),
      currency: term(),
      currency_alpha_next_to_number: term(),
      currency_long: term(),
      currency_no_symbol: term(),
      currency_short: term(),
      currency_spacing: term(),
      decimal_long: term(),
      decimal_short: term(),
      other: term(),
      percent: term(),
      rational: term(),
      scientific: term(),
      standard: term()
    }

## Functions

# all_formats_for(locale)

    @spec all_formats_for(Localize.LanguageTag.t() | atom() | String.t()) ::
      {:ok, map()} | {:error, Exception.t()}

Returns all number formats defined for a locale, keyed by number system.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- `{:ok, formats_map}` where `formats_map` is a map of `%{system_name => Localize.Number.Format.t()}`.

- `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> {:ok, formats} = Localize.Number.Format.all_formats_for(:en)
    iex> Map.has_key?(formats, :latn)
    true

# all_formats_for!(locale)

    @spec all_formats_for!(Localize.LanguageTag.t() | atom() | String.t()) :: map()

Same as `all_formats_for/1` but raises on error.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- A map of formats keyed by number system.

### Raises

- Raises an exception if the locale data cannot be loaded.

# currency_spacing(locale, number_system \\ :default)

    @spec currency_spacing(
      Localize.LanguageTag.t() | atom() | String.t(),
      atom() | String.t()
    ) :: map() | {:error, Exception.t()}

Returns the currency spacing rules for a locale and number system.

Currency spacing defines how to insert whitespace between a currency symbol and the adjacent number.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

- `number_system` is a number system name or type atom. The default is `:default`.

### Returns

- A map with `:before_currency` and `:after_currency` keys, each containing spacing rules.

- `{:error, exception}` if the locale data cannot be loaded.

# default_grouping_for(locale)

    @spec default_grouping_for(Localize.LanguageTag.t() | atom() | String.t()) ::
      {:ok, map()} | {:error, Exception.t()}

Returns the default grouping definition for a locale.

The grouping defines how integer and fraction digits are grouped with separators in the standard number format.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- `{:ok, grouping}` where `grouping` is a map with `:integer` and `:fraction` keys, each containing `:first` and `:rest` group sizes.

- `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> Localize.Number.Format.default_grouping_for(:en)
    {:ok, %{fraction: %{first: 0, rest: 0}, integer: %{first: 3, rest: 3}}}

# default_grouping_for!(locale)

    @spec default_grouping_for!(Localize.LanguageTag.t() | atom() | String.t()) :: %{
      fraction: %{first: 0, rest: 0},
      integer: %{first: non_neg_integer(), rest: non_neg_integer()}
    }

Same as `default_grouping_for/1` but raises on error.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- A grouping map.

### Raises

- Raises an exception if the locale data cannot be loaded.

### Examples

    iex> Localize.Number.Format.default_grouping_for!(:en)
    %{fraction: %{first: 0, rest: 0}, integer: %{first: 3, rest: 3}}

# format_styles_for(locale, number_system \\ :default)

    @spec format_styles_for(
      Localize.LanguageTag.t() | atom() | String.t(),
      atom() | String.t()
    ) :: {:ok, [atom()]} | {:error, Exception.t()}

Returns the format styles available for a locale and number system.

Format styles standardise access to formats for common use cases such as `:standard`, `:currency`, `:accounting`, `:scientific`, `:percent`, etc.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

- `number_system` is a number system name or type atom. The default is `:default`.

### Returns

- `{:ok, styles}` where `styles` is a list of format style atoms.

- `{:error, exception}` if the locale data cannot be loaded.

# format_system_names_for(locale)

    @spec format_system_names_for(Localize.LanguageTag.t() | atom() | String.t()) ::
      {:ok, [atom()]} | {:error, Exception.t()}

Returns the number system names available for a locale.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- `{:ok, names}` where `names` is a list of unique number system name atoms.

- `{:error, exception}` if the locale data cannot be loaded.

# format_system_types_for(locale)

    @spec format_system_types_for(Localize.LanguageTag.t() | atom() | String.t()) ::
      {:ok, [atom()]} | {:error, Exception.t()}

Returns the number system types available for a locale.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- `{:ok, types}` where `types` is a list of system type atoms (e.g., `[:default, :native]`).

- `{:error, exception}` if the locale data cannot be loaded.

# formats_for(locale, number_system \\ :default)

    @spec formats_for(
      Localize.LanguageTag.t() | atom() | String.t(),
      atom() | String.t()
    ) :: {:ok, t()} | {:error, Exception.t()}

Returns the format definitions for a given locale and number system.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

- `number_system` is a number system name or type atom. The default is `:default`.

### Returns

- `{:ok, Localize.Number.Format.t()}` with the format definitions.

- `{:error, exception}` if the locale data cannot be loaded or the number system is not available.

# formats_for!(locale, number_system \\ :default)

    @spec formats_for!(
      Localize.LanguageTag.t() | atom() | String.t(),
      atom() | String.t()
    ) :: t()

Same as `formats_for/2` but raises on error.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

- `number_system` is a number system name or type atom. The default is `:default`.

### Returns

- A `Localize.Number.Format.t()` struct.

### Raises

- Raises an exception if the locale or number system is invalid.

# minimum_grouping_digits_for(locale)

    @spec minimum_grouping_digits_for(Localize.LanguageTag.t() | atom() | String.t()) ::
      {:ok, non_neg_integer()} | {:error, Exception.t()}

Returns the minimum grouping digits for a locale.

This determines the minimum number of digits before grouping separators are applied. For example, if the minimum is 2, the number 1000 would be formatted as "1000" rather than "1,000".

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- `{:ok, minimum_digits}` where `minimum_digits` is a non-negative integer.

- `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> Localize.Number.Format.minimum_grouping_digits_for(:en)
    {:ok, 1}

# minimum_grouping_digits_for!(locale)

    @spec minimum_grouping_digits_for!(Localize.LanguageTag.t() | atom() | String.t()) ::
      non_neg_integer()

Same as `minimum_grouping_digits_for/1` but raises on error.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

### Returns

- The minimum grouping digits as an integer.

### Raises

- Raises an exception if the locale data cannot be loaded.

### Examples

    iex> Localize.Number.Format.minimum_grouping_digits_for!(:en)
    1

# misc_patterns_for(locale, number_system \\ :latn)

    @spec misc_patterns_for(Localize.locale(), atom()) ::
      {:ok, map()} | {:error, Exception.t()}

Returns the miscellaneous number patterns for a locale and number system.

These patterns include range, approximately, at-least, and at-most formatting templates.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0`.

- `number_system` is a number system name atom. The default is `:latn`.

### Returns

- `{:ok, patterns}` where `patterns` is a map with keys `:range`, `:approximately`, `:at_least`, and `:at_most`.

- `{:error, exception}` if the locale or number system data cannot be loaded.

### Examples

    iex> {:ok, patterns} = Localize.Number.Format.misc_patterns_for(:en)
    iex> patterns.range
    [0, "–", 1]

# short_format_styles()

    @spec short_format_styles() :: [
      :decimal_long | :decimal_short | :currency_short | :currency_long,
      ...
    ]

Returns the short format style names.

### Returns

- A list of atoms: `[:decimal_long, :decimal_short, :currency_short, :currency_long]`.

# short_format_styles_for(locale, number_system \\ :default)

    @spec short_format_styles_for(
      Localize.LanguageTag.t() | atom() | String.t(),
      atom() | String.t()
    ) :: {:ok, [atom()]} | {:error, Exception.t()}

Returns the short format styles available for a locale and number system.

### Arguments

- `locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0` struct.

- `number_system` is a number system name or type atom. The default is `:default`.

### Returns

- `{:ok, styles}` where `styles` is a list of short format style atoms.

- `{:error, exception}` if the locale data cannot be loaded.