# `Cldr.Unit.Format`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit/format.ex#L1)

Functions for formatting a unit or unit range into
an iolist or a string.

# `grammar`
*since 3.5.0* 

```elixir
@spec grammar(Cldr.Unit.t(), Keyword.t()) ::
  grammar_list() | {grammar_list(), grammar_list()}
```

Traverses the components of a unit
and resolves a list of base units with
their gramatical case and plural selector
definitions for a given locale.

This function relies upon the internal
representation of units and grammatical features
and is primarily for the support of
formatting a function through `Cldr.Unit.to_string/2`.

## Arguments

* `unit` is a `t:Cldr.Unit.t/0` or a binary
  unit string

## Options

* `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
  or a `t:Cldr.LanguageTag` struct.  The default is `Cldr.get_locale/0`

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

## Returns

## Examples

# `to_iolist`

```elixir
@spec to_iolist(list_or_number :: Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t()]) ::
  {:ok, String.t()} | {:error, {atom(), binary()}}
```

Formats a number into an iolist according to a unit definition
for the current process's locale and backend.

See `Cldr.Unit.Format.to_iolist/3` for full details.

# `to_iolist`

Formats a number into an iolist according to a unit definition
for a locale.

## Arguments

* `list_or_unit` is any number (integer, float or Decimal) or a
  `t:Cldr.Unit.t/0` struct or a list of `t:Cldr.Unit.t/0` structs or a
  `t:Cldr.Unit.Range.t/0` struct.

* `options` is a keyword list

## Options

* `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if
  the number to be formatted is a `t:Cldr.Unit.t/0` struct

* `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
  or a `Cldr.LanguageTag` struct.  The default is `Cldr.get_locale/0`

* `:style` is one of those returned by `Cldr.Unit.known_styles/0`.
  The current styles are `:long`, `:short` and `:narrow`.
  The default is `style: :long`

* `:grammatical_case` indicates that a localisation for the given
  locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0`
  for the list of known grammatical cases. Note that not all locales
  define all cases. However all locales do define the `:nominative`
  case, which is also the default.

* `:gender` indicates that a localisation for the given
  locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0`
  for the list of known grammatical genders. Note that not all locales
  define all genders.

* `:list_options` is a keyword list of options for formatting a list
  which is passed through to `Cldr.List.to_string/3`. This is only
  applicable when formatting a list of units.

* Any other options are passed to `Cldr.Number.to_string/2`
  which is used to format the `number`

## Returns

* `{:ok, io_list}` or

* `{:error, {exception, message}}`

## Examples

    iex> Cldr.Unit.Format.to_iolist Cldr.Unit.new!(:gallon, 123)
    {:ok, ["123", " gallons"]}

# `to_iolist!`

```elixir
@spec to_iolist!(Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t(), ...]) ::
  list() | no_return()
```

Formats a number into an iolist according to a unit definition
for the current process's locale and backend.

See `Cldr.Unit.Format.to_iolist!/3` for full details.

# `to_iolist!`

Formats a unit using `to_iolist/3` but raises if there is
an error.

## Arguments

* `number` is any number (integer, float or Decimal) or a
  `t:Cldr.Unit.t/0` struct or a list of `t:Cldr.Unit.t/0` structs or a
  `t:Cldr.Unit.Range.t/0` struct.

* `options` is a keyword list

## Options

* `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if
  the number to be formatted is a `t:Cldr.Unit.t/0` struct

* `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
  or a `Cldr.LanguageTag` struct.  The default is `Cldr.get_locale/0`

* `:style` is one of those returned by `Cldr.Unit.known_styles/0`.
  The current styles are `:long`, `:short` and `:narrow`.
  The default is `style: :long`.

* `:grammatical_case` indicates that a localisation for the given
  locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0`
  for the list of known grammatical cases. Note that not all locales
  define all cases. However all locales do define the `:nominative`
  case, which is also the default.

* `:gender` indicates that a localisation for the given
  locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0`
  for the list of known grammatical genders. Note that not all locales
  define all genders.

* `:list_options` is a keyword list of options for formatting a list
  which is passed through to `Cldr.List.to_string/3`. This is only
  applicable when formatting a list of units.

* Any other options are passed to `Cldr.Number.to_string/2`
  which is used to format the `number`

## Returns

* `io_list` or

* raises an exception

## Examples

    iex> Cldr.Unit.Format.to_iolist! 123, unit: :gallon
    ["123", " gallons"]

# `to_string`

```elixir
@spec to_string(list_or_number :: Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t()]) ::
  {:ok, String.t()} | {:error, {atom(), binary()}}
```

Formats a number into a string according to a unit definition
using the current process's locale and backend.

See `Cldr.Unit.to_string/3` for full details.

# `to_string`

```elixir
@spec to_string(
  Cldr.Unit.value() | Cldr.Unit.t() | Cldr.Unit.Range.t() | [Cldr.Unit.t()],
  Cldr.backend() | Keyword.t(),
  Keyword.t() | map()
) :: {:ok, String.t()} | {:error, {atom(), binary()}}
```

Formats a unit or unit range or a number into a string according to a unit
definition for a locale.

During processing any `:format_options` of a `t:Cldr.Unit.t/0` are merged
into the `options` argument.

## Arguments

* `list_or_unit` is any number (integer, float or Decimal) or a
  `t:Cldr.Unit.t/0` struct or a list of `t:Cldr.Unit.t/0` structs or a
  `t:Cldr.Unit.Range.t/0` struct.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

* `options` is a keyword list of options.

## Options

* `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if
  the number to be formatted is a `t:Cldr.Unit.t/0` struct.

* `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
  or a `Cldr.LanguageTag` struct.  The default is `Cldr.get_locale/0`.

* `style` is one of those returned by `Cldr.Unit.known_styles/0`.
  The current styles are `:long`, `:short` and `:narrow`.
  The default is `style: :long`.

* `:grammatical_case` indicates that a localisation for the given
  locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0`
  for the list of known grammatical cases. Note that not all locales
  define all cases. However all locales do define the `:nominative`
  case, which is also the default.

* `:gender` indicates that a localisation for the given
  locale and given grammatical gender should be used.
  See `Cldr.Unit.known_grammatical_genders/0`
  for the list of known grammatical genders. Note that not all locales
  define all genders.

* `:list_options` is a keyword list of options for formatting a list
  which is passed through to `Cldr.List.to_string/3`. This is only
  applicable when formatting a list of units.

* Any other options are passed to `Cldr.Number.to_string/2`
  which is used to format the `number`.

## Returns

* `{:ok, formatted_string}` or

* `{:error, {exception, message}}`

## Examples

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
    {:ok, "123 gallons"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 1), MyApp.Cldr
    {:ok, "1 gallon"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 1), MyApp.Cldr, locale: "af"
    {:ok, "1 gelling"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 1), MyApp.Cldr, locale: "bs"
    {:ok, "1 galon"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 1234), MyApp.Cldr, format: :long
    {:ok, "1 thousand gallons"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 1234), MyApp.Cldr, format: :short
    {:ok, "1K gallons"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:megahertz, 1234), MyApp.Cldr
    {:ok, "1,234 megahertz"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(:megahertz, 1234), MyApp.Cldr, style: :narrow
    {:ok, "1,234MHz"}

    iex> {:ok, range} = Cldr.Unit.Range.new(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 5))
    iex> Cldr.Unit.to_string(range, locale: :ja)
    {:ok, "1～5 グラム"}

    iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(123, :foot), MyApp.Cldr
    {:ok, "123 feet"}

    iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :foot
    {:ok, "123 feet"}

    iex> Cldr.Unit.Format.to_string Decimal.new(123), MyApp.Cldr, unit: :foot
    {:ok, "123 feet"}

    iex> Cldr.Unit.to_string Cldr.Unit.new!(2, "curr-usd-per-gallon"), MyApp.Cldr
    {:ok, "$2.00 per gallon"}

    iex> Cldr.Unit.to_string Cldr.Unit.new!(2, "gallon-per-curr-usd"), MyApp.Cldr
    {:ok, "2 gallons per US dollar"}

    iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :megabyte, locale: "en", style: :unknown
    {:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}

    iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :megabyte, locale: "en",
    ...> grammatical_gender: :feminine
    {:error, {Cldr.UnknownGrammaticalGenderError,
      "The locale :en does not define a grammatical gender :feminine. The valid genders are [:masculine]"
    }}

# `to_string!`

```elixir
@spec to_string!(
  list_or_number :: Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t()]
) ::
  String.t() | no_return()
```

Formats a unit or unit range or a number into a string according to a unit
definition for the current locale.

During processing any `:format_options` of a `t:Cldr.Unit.t/0` are merged
into the `options` argument.

The current process's locale is set with `Cldr.put_locale/1`.

See `Cldr.Unit.to_string!/3` for full details.

# `to_string!`

```elixir
@spec to_string!(
  Cldr.Unit.value() | Cldr.Unit.t() | Cldr.Unit.Range.t() | [Cldr.Unit.t()],
  Cldr.backend() | Keyword.t(),
  Keyword.t() | map()
) :: String.t() | no_return()
```

Formats a unit or unit range or a number into a string according to a unit
definition for a locale. Raises on error.

During processing any `:format_options` of a `t:Cldr.Unit.t/0` are merged
into the `options` argument.

During processing any `:format_options` of a `t:Cldr.Unit.t/0` are merged with
`options` with `options` taking precedence.

## Arguments

* `number_or_unit` is any number (integer, float or Decimal) or a
  `t:Cldr.Unit.t/0` struct or a list of `t:Cldr.Unit.t/0` structs or a
  `t:Cldr.Unit.Range.t/0` struct.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

* `options` is a keyword list.

## Options

* `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if
  the number to be formatted is a `t:Cldr.Unit.t/0` struct.

* `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
  or a `Cldr.LanguageTag` struct.  The default is `Cldr.get_locale/0`.

* `:style` is one of those returned by `Cldr.Unit.known_styles/0`.
  The current styles are `:long`, `:short` and `:narrow`.
  The default is `style: :long`.

* Any other options are passed to `Cldr.Number.to_string/2`
  which is used to format the `number`.

## Returns

* `formatted_string` or

* raises an exception

## Examples

    iex> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
    "123 gallons"

    iex> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr
    "1 gallon"

    iex> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr, locale: "af"
    "1 gelling"

    iex> {:ok, range} = Cldr.Unit.Range.new(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 5))
    iex> Cldr.Unit.to_string!(range, locale: :ja)
    "1～5 グラム"

# `traverse`

Traverses a unit's decomposition and invokes
a function on each node of the composition
tree.

## Arguments

* `unit` is any unit returned by `Cldr.Unit.new/2`

* `fun` is any single-arity function. It will be invoked
  for each node of the composition tree. The argument is a tuple
  of the following form:

  * `{:unit, argument}`
  * `{:times, {argument_1, argument_2}}`
  * `{:prefix, {prefix_unit, argument}}`
  * `{:power, {power_unit, argument}}`
  * `{:per, {argument_1, argument_2}}`

  Where the arguments are the results returned
  from the `fun/1`.

## Returns

The result returned from `fun/1`

---

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