# `Cldr.List`
[🔗](https://github.com/elixir-cldr/cldr_lists/blob/v2.12.2/lib/cldr/list.ex#L1)

Cldr module to formats lists.

If we have a list of days like `["Monday", "Tuesday", "Wednesday"]`
then we can format that list for a given locale by:

    iex> Cldr.List.to_string(["Monday", "Tuesday", "Wednesday"], MyApp.Cldr, locale: "en")
    {:ok, "Monday, Tuesday, and Wednesday"}

# `pattern_type`

```elixir
@type pattern_type() ::
  :or
  | :or_narrow
  | :or_short
  | :standard
  | :standard_narrow
  | :standard_short
  | :unit
  | :unit_narrow
  | :unit_short
```

# `intersperse`

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

Intersperses a list elements into a list format according to the list
pattern rules for a locale.

This function can be helpful when creating a list from `Phoenix`
safe strings which are of the format `{:safe, "some string"}`.

## Arguments

* `list` is any list of of terms.

* `options` is a keyword list.

## Options

* `:locale` is any configured locale. See `Cldr.known_locale_names/1`. The default
  is `locale: Cldr.get_locale/1`.

* `:format` is any of those returned by
  `Cldr.List.known_list_formats/0` or by `Cldr.List.Pattern.new/1`.
  The default is `format: :standard`.

* `:treat_middle_as_end` is a boolean value indicating whether, when
  formatting the last element of a list, to use the `:end` pattern (which
  typically includes a localized " and " pattern) or to use the `:middle`
  pattern which does not include such a pattern. The default is `false`
  meaning "use the :end pattern". Note that this option is effective
  only when the list contains three or more element.

## Examples

    iex> Cldr.List.intersperse(["a", "b", "c"], MyApp.Cldr, locale: :en)
    {:ok, ["a", ", ", "b", ", and ", "c"]}

    iex> Cldr.List.intersperse(["a", "b", "c"], MyApp.Cldr, locale: :en, format: :unit_narrow)
    {:ok, ["a", " ", "b", " ", "c"]}

    iex> Cldr.List.intersperse(["a", "b", "c"], MyApp.Cldr, locale: :fr)
    {:ok, ["a", ", ", "b", " et ", "c"]}

    iex> Cldr.List.intersperse([1,2,3,4,5,6], MyApp.Cldr)
    {:ok, [1, ", ", 2, ", ", 3, ", ", 4, ", ", 5, ", and ", 6]}

    iex> Cldr.List.intersperse(["a"], MyApp.Cldr)
    {:ok, ["a"]}

    iex> Cldr.List.intersperse([1,2], MyApp.Cldr)
    {:ok, [1, " and ", 2]}

# `intersperse!`

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

Formats a list using `intersperse/2` but raises if there is
an error.

## Examples

    iex> Cldr.List.intersperse!(["a", "b", "c"], MyApp.Cldr, locale: :en)
    ["a", ", ", "b", ", and ", "c"]

    iex> Cldr.List.intersperse!(["a", "b", "c"], MyApp.Cldr, locale: :en, format: :unit_narrow)
    ["a", " ", "b", " ", "c"]

# `known_list_formats`

Return the list of known list formats.

## Example

    iex> Cldr.List.known_list_formats()
    [:or, :or_narrow, :or_short, :standard, :standard_narrow,
      :standard_short, :unit, :unit_narrow, :unit_short]

# `known_list_styles`

> This function is deprecated. Use Cldr.List.known_list_formats/0.

# `list_formats_for`

```elixir
@spec list_formats_for(Cldr.Locale.locale_name(), Cldr.backend() | nil) ::
  [atom()] | {:error, {module(), String.t()}}
```

Returns the formats of list patterns available for a locale.

Returns a list of `atom`s of of the list formats that are
available in CLDR for a locale.

## Example

    iex> Cldr.List.list_formats_for("en", MyApp.Cldr)
    [:or, :or_narrow, :or_short, :standard, :standard_narrow,
      :standard_short, :unit, :unit_narrow, :unit_short]

# `list_patterns_for`

```elixir
@spec list_patterns_for(Cldr.Locale.locale_name(), Cldr.backend() | nil) ::
  map() | {:error, {module(), String.t()}}
```

Returns the list patterns for a locale.

List patterns provide rules for combining multiple
items into a language format appropriate for a locale.

## Example

    iex> Cldr.List.list_patterns_for(:en, MyApp.Cldr)
    %{
      or: %Cldr.List.Pattern{
        two: [0, " or ", 1],
        end: [0, ", or ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      or_narrow: %Cldr.List.Pattern{
        two: [0, " or ", 1],
        end: [0, ", or ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      or_short: %Cldr.List.Pattern{
        two: [0, " or ", 1],
        end: [0, ", or ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      standard: %Cldr.List.Pattern{
        two: [0, " and ", 1],
        end: [0, ", and ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      standard_narrow: %Cldr.List.Pattern{
        two: [0, ", ", 1],
        end: [0, ", ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      standard_short: %Cldr.List.Pattern{
        two: [0, " & ", 1],
        end: [0, ", & ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      unit: %Cldr.List.Pattern{
        two: [0, ", ", 1],
        end: [0, ", ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      },
      unit_narrow: %Cldr.List.Pattern{
        two: [0, " ", 1],
        end: [0, " ", 1],
        middle: [0, " ", 1],
        start: [0, " ", 1]
      },
      unit_short: %Cldr.List.Pattern{
        two: [0, ", ", 1],
        end: [0, ", ", 1],
        middle: [0, ", ", 1],
        start: [0, ", ", 1]
      }
    }

# `list_styles_for`

> This function is deprecated. Use Cldr.List.list_formats_for/2.

# `to_string`

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

Formats a list into a string according to the list pattern rules for a locale.

## Arguments

* `list` is any list of of terms that can be passed through `Kernel.to_string/1`.

* `options` is a keyword list.

## Options

* `:locale` is any configured locale. See `Cldr.known_locale_names/0`. The default
  is `locale: Cldr.get_locale/1`

* `:format` is any of those returned by
  `Cldr.List.known_list_formats/0` or by `Cldr.List.Pattern.new/1`.
  The default is `format: :standard`.

* `:treat_middle_as_end` is a boolean value indicating whether, when
  formatting the last element of a list, to use the `:end` pattern (which
  typically includes a localized " and " pattern) or to use the `:middle`
  pattern which does not include such a pattern. The default is `false`
  meaning "use the :end pattern". Note that this option is effective
  only when the list contains three or more element.

## Examples

    iex> Cldr.List.to_string(["a", "b", "c"], MyApp.Cldr, locale: :en)
    {:ok, "a, b, and c"}

    iex> Cldr.List.to_string(["a", "b", "c"], MyApp.Cldr, locale: :en, format: :unit_narrow)
    {:ok, "a b c"}

    iex> Cldr.List.to_string(["a", "b", "c"], MyApp.Cldr, locale: :fr)
    {:ok, "a, b et c"}

    iex> Cldr.List.to_string([1,2,3,4,5,6], MyApp.Cldr)
    {:ok, "1, 2, 3, 4, 5, and 6"}

    iex> Cldr.List.to_string(["a"], MyApp.Cldr)
    {:ok, "a"}

    iex> Cldr.List.to_string([1,2], MyApp.Cldr)
    {:ok, "1 and 2"}

# `to_string!`

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

Formats a list using `to_string/2` but raises if there is
an error.

## Examples

    iex> Cldr.List.to_string!(["a", "b", "c"], MyApp.Cldr, locale: "en")
    "a, b, and c"

    iex> Cldr.List.to_string!(["a", "b", "c"], MyApp.Cldr, locale: "en", format: :unit_narrow)
    "a b c"

---

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