# `Unity.Formatter`
[🔗](https://github.com/elixir-localize/unity/blob/v0.6.0/lib/unity/formatter.ex#L1)

Formats evaluation results for display in terse, verbose, or
locale-aware modes.

The formatter delegates to `Localize.Unit.to_string/2` for unit
formatting and `Localize.Number.to_string/2` for bare numbers.

# `format`

```elixir
@type format() :: :default | :verbose | :terse
```

# `options`

```elixir
@type options() :: [
  format: format(),
  locale: atom() | String.t(),
  input: String.t(),
  digits: pos_integer(),
  exponential: boolean(),
  output_format: String.t(),
  show_reciprocal: boolean()
]
```

# `format`

```elixir
@spec format(
  Localize.Unit.t() | number(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}
```

Formats a result value for display.

### Arguments

* `result` - a `Localize.Unit.t()` or a number.

* `options` - keyword list of formatting options.

### Options

* `:format` - output format. `:default` shows the value and unit name,
  `:verbose` shows `from = to` format, `:terse` shows only the numeric
  value. Defaults to `:default`.

* `:locale` - locale for number and unit formatting. Defaults to the
  current process locale.

* `:input` - the original input string, used in verbose mode.

* `:digits` - maximum number of fractional digits to display.
  Defaults to 6.

* `:exponential` - if `true`, format numbers in scientific notation.
  Defaults to `false`.

* `:output_format` - a printf-style format string (e.g., `"%.8g"`).
  When set, overrides `:digits` and `:exponential`.

* `:show_reciprocal` - if `true`, append a reciprocal conversion line
  (e.g., `/ 0.3048`). Defaults to `true` in `:default` format for
  conversions. Set to `false` with `--strict` or `--one-line`.

### Returns

* `{:ok, formatted_string}` on success.

* `{:error, reason}` on failure.

### Examples

    iex> {:ok, unit} = Localize.Unit.new(9.84252, "foot")
    iex> Unity.Formatter.format(unit)
    {:ok, "9.84252 feet"}

# `format!`

```elixir
@spec format!(
  Localize.Unit.t() | number(),
  keyword()
) :: String.t()
```

Formats a result value for display, raising on failure.

---

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