Icu.List (icu v0.4.0)

Locale-aware conjunctions for enumerables.

format/2 wraps the ICU4X list formatter so you can turn Elixir enumerables into natural-language lists using the application locale (configurable via :icu, :default_locale). Reach for Icu.List.Formatter.new/1 whenever you need to reuse the same locale or style across multiple calls.

Examples

iex> Icu.List.format(["Foo", "Bar"])
{:ok, "Foo and Bar"}

iex> Icu.List.format(["Uno", "Dos", "Tres"], locale: "es")
{:ok, "Uno, Dos y Tres"}

Options

  • :type – conjunction style to use (:and, :or, or :unit).
  • :width – textual width (:wide, :short, or :narrow) that trades context for brevity.
  • :locale – override the locale used for formatting; defaults to the application locale.

Summary

Types

format_error()
formatter()

Opaque reference to an ICU4X list formatter.

options()

Map form of the supported options.

options_input()
options_list()

Keyword form of the supported options.

type()

Controls the conjunction type applied between list items.

width()

Controls the stylistic width of conjunctions.

Functions

format(values, options \\ [])

Formats an enumerable of values.

format!(values, options \\ [])

Convenience helper that raises on error.

format_to_parts(values, options \\ [])

Formats values into discrete parts.

format_to_parts!(values, options \\ [])

Formats to parts and raises on error.

Types

format_error()

@type format_error() ::
  :invalid_formatter | :invalid_locale | :invalid_options | :invalid_items

formatter()

@type formatter() :: Icu.List.Formatter.t()

Opaque reference to an ICU4X list formatter.

options()

@type options() :: %{
  optional(:type) => type(),
  optional(:width) => width(),
  optional(:locale) => Icu.LanguageTag.t() | nil
}

Map form of the supported options.

options_input()

@type options_input() :: options() | options_list() | nil

options_list()

@type options_list() :: [
  type: type(),
  width: width(),
  locale: Icu.LanguageTag.t() | nil
]

Keyword form of the supported options.

type()

@type type() :: :and | :or | :unit

Controls the conjunction type applied between list items.

width()

@type width() :: :wide | :short | :narrow

Controls the stylistic width of conjunctions.

Functions

format(values, options \\ [])

@spec format(Enumerable.t(), options_input()) ::
  {:ok, String.t()} | {:error, format_error()}

Formats an enumerable of values.

Returns {:ok, String.t()} on success or an error tuple when the input cannot be coerced into a non-empty list.

Examples

iex> Icu.List.format(["Foo", "Bar"])
{:ok, "Foo and Bar"}

iex> Icu.List.format(1..3, type: :or)
{:ok, "1, 2, or 3"}

format!(values, options \\ [])

@spec format!(Enumerable.t(), options_input()) :: String.t()

Convenience helper that raises on error.

Examples

iex> Icu.List.format!(["Foo", "Bar", "Baz"])
"Foo, Bar, and Baz"

format_to_parts(values, options \\ [])

@spec format_to_parts(Enumerable.t(), options_input()) ::
  {:ok, [map()]} | {:error, format_error()}

Formats values into discrete parts.

Returns each literal and element as a tagged map so the caller can apply custom rendering (for example when interleaving HTML tags).

Examples

iex> {:ok, parts} = Icu.List.format_to_parts(["A", "B", "C"])
iex> Enum.map(parts, & &1.part_type)
[:element, :literal, :element, :literal, :element]

format_to_parts!(values, options \\ [])

@spec format_to_parts!(Enumerable.t(), options_input()) :: [map()]

Formats to parts and raises on error.

Examples

iex> Icu.List.format_to_parts!(["Foo"])
[%{part_type: :element, value: "Foo"}]