# `Localize.Number.Format`
[🔗](https://github.com/elixir-localize/localize/blob/v0.38.0/lib/localize/number/format.ex#L1)

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.

# `format`

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

# `t`

```elixir
@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()
}
```

# `all_formats_for`

```elixir
@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
  `t: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!`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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!`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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!`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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!`

```elixir
@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
  `t: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`

```elixir
@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
  `t: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`

```elixir
@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`

```elixir
@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
  `t: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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*