@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"}

@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"

@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"}
]}

@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