@spec format(Localize.Duration.t() | map(), Keyword.t()) ::
  {:ok, String.t()} | {:error, term()}

Formats a duration according to locale conventions.

Arguments

• duration is a Localize.Duration struct or a map with any of the keys :years, :months, :days, :hours, :minutes, :seconds (plural, matching the JS API), or the singular Elixir equivalents :year, :month, :day, :hour, :minute, :second.

• options is a keyword list of options.

Options

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

• :style is :long, :short, or :narrow. The default is :long.

• Per-unit style options — :years, :months, :days, :hours, :minutes, :seconds, :microseconds — each accept :long, :short, or :narrow, overriding :style for that unit (JS hours: "narrow").

• Per-unit display options — :years_display, :months_display, :days_display, :hours_display, :minutes_display, :seconds_display, :microseconds_display — each accept :auto (omit when zero, the default) or :always (JS hoursDisplay).

Returns

• {:ok, formatted_string} on success.

• {:error, reason} if the duration or options are invalid.

Examples

iex> {:ok, d} = Localize.Duration.new(~D[2019-01-01], ~D[2019-12-31])
iex> Intl.DurationFormat.format(d, locale: :en)
{:ok, "11 months and 30 days"}

iex> Intl.DurationFormat.format(%{hours: 2, minutes: 30}, locale: :en)
{:ok, "2 hours and 30 minutes"}

iex> Intl.DurationFormat.format(%{hours: 2}, locale: :en, minutes_display: :always)
{:ok, "2 hours and 0 minutes"}

iex> Intl.DurationFormat.format(%{hours: 2, minutes: 30}, locale: :en, hours: :narrow)
{:ok, "2h and 30 minutes"}

@spec format!(Localize.Duration.t() | map(), Keyword.t()) :: String.t() | no_return()

Formats a duration, raising on error.

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

Arguments

• duration is a Localize.Duration struct or a map.

• options is a keyword list of options.

Returns

• A formatted string.

Examples

iex> Intl.DurationFormat.format!(%{hours: 2, minutes: 30}, locale: :en)
"2 hours and 30 minutes"

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

Formats a duration into a list of typed parts.

Modelled on the JS Intl.DurationFormat.formatToParts(). Each duration field contributes its unit parts, with the numeric segments carrying a :unit key naming the field; the separators between fields are :literal parts.

Arguments

• duration is a Localize.Duration struct or a map with duration component keys.

• options is a keyword list of options. Accepts the same options as format/2, including the per-unit style and display options.

Returns

• {:ok, parts} where parts is a list of %{type: atom, value: String.t()} maps; numeric parts also carry a :unit key.

• {:error, reason} if the duration or options are invalid.

Examples

iex> Intl.DurationFormat.format_to_parts(%{hours: 2, minutes: 30}, locale: :en)
{:ok, [
  %{type: :integer, value: "2", unit: :hour},
  %{type: :literal, value: " "},
  %{type: :unit, value: "hours"},
  %{type: :literal, value: " and "},
  %{type: :integer, value: "30", unit: :minute},
  %{type: :literal, value: " "},
  %{type: :unit, value: "minutes"}
]}

@spec format_to_parts!(Localize.Duration.t() | map(), Keyword.t()) ::
  [%{type: atom(), value: String.t()}] | no_return()

Formats a duration into typed parts, raising on error.

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

Arguments

• duration is a Localize.Duration struct or a map.

• options is a keyword list of options.

Returns

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

Examples

iex> Intl.DurationFormat.format_to_parts!(%{hours: 2}, locale: :en) |> length()
3