# `Intl.ListFormat`
[🔗](https://github.com/elixir-localize/intl/blob/v1.1.0/lib/intl/list_format.ex#L1)

Locale-sensitive list formatting, modelled on
[`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat).

Joins a list of items into a human-readable string using
locale-appropriate conjunctions ("and"), disjunctions ("or"),
or unit-style separators.

Delegates to `Localize.List` for the underlying formatting.

# `format`

```elixir
@spec format([term()], Keyword.t()) :: {:ok, String.t()} | {:error, term()}
```

Formats a list into a locale-aware string.

### Arguments

* `list` is a list of terms that implement `String.Chars`.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier string or atom. The default
  is the current process locale.

* `:type` is `:conjunction`, `:disjunction`, or `:unit`.
  The default is `:conjunction`.

* `:style` is `:long`, `:short`, or `:narrow`.
  The default is `:long`.

### Returns

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

* `{:error, reason}` if the locale or options are invalid.

### Examples

    iex> Intl.ListFormat.format(["a", "b", "c"], locale: :en)
    {:ok, "a, b, and c"}

    iex> Intl.ListFormat.format(["a", "b", "c"], locale: :en, type: :disjunction)
    {:ok, "a, b, or c"}

    iex> Intl.ListFormat.format(["a", "b"], locale: :en, type: :unit, style: :narrow)
    {:ok, "a b"}

# `format!`

```elixir
@spec format!([term()], Keyword.t()) :: String.t() | no_return()
```

Formats a list into a locale-aware string, raising on error.

Same as `format/2` but returns the string directly or raises.

### Arguments

* `list` is a list of terms that implement `String.Chars`.

* `options` is a keyword list of options.

### Returns

* A formatted string.

### Examples

    iex> Intl.ListFormat.format!(["a", "b", "c"], locale: :en)
    "a, b, and c"

# `format_to_parts`

```elixir
@spec format_to_parts([term()], Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, term()}
```

Formats a list into typed parts.

Modelled on the JS `Intl.ListFormat.formatToParts()`. Each list
element becomes an `:element` part and each separator becomes a
`:literal` part.

### Arguments

* `list` is a list of terms that implement `String.Chars`.

* `options` is a keyword list of options. Accepts the same
  options as `format/2`.

### Returns

* `{:ok, parts}` where `parts` is a list of
  `%{type: atom, value: String.t()}` maps.

* `{:error, reason}` if the locale or options are invalid.

### Examples

    iex> Intl.ListFormat.format_to_parts(["a", "b", "c"], locale: :en)
    {:ok, [
      %{type: :element, value: "a"},
      %{type: :literal, value: ", "},
      %{type: :element, value: "b"},
      %{type: :literal, value: ", and "},
      %{type: :element, value: "c"}
    ]}

# `format_to_parts!`

```elixir
@spec format_to_parts!([term()], Keyword.t()) ::
  [%{type: atom(), value: String.t()}] | no_return()
```

Formats a list into typed parts, raising on error.

Same as `format_to_parts/2` but returns the parts directly or raises.

### Arguments

* `list` is a list of terms that implement `String.Chars`.

* `options` is a keyword list of options.

### Returns

* A list of `%{type: atom, value: String.t()}` maps.

### Examples

    iex> Intl.ListFormat.format_to_parts!(["a", "b"], locale: :en) |> length()
    3

---

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