@spec format(integer(), atom(), Keyword.t()) :: {:ok, String.t()} | {:error, term()}

Formats a relative time value.

Arguments

• value is an integer representing the offset. Negative values indicate the past (for example, -1 for "1 day ago"), positive values indicate the future (for example, 2 for "in 2 hours").

• unit is the time unit atom: :second, :minute, :hour, :day, :week, :month, :year, or :quarter.

• 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.

• :numeric is :always or :auto. When :auto, special forms like "yesterday" and "tomorrow" are used where the locale defines them. When :always, numeric forms like "1 day ago" and "in 1 day" are always used. The default is :auto.

Returns

• {:ok, formatted_string} on success.

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

Examples

iex> Intl.RelativeTimeFormat.format(-1, :day, locale: :en)
{:ok, "yesterday"}

iex> Intl.RelativeTimeFormat.format(2, :hour, locale: :en)
{:ok, "in 2 hours"}

iex> Intl.RelativeTimeFormat.format(-3, :day, locale: :en)
{:ok, "3 days ago"}

iex> Intl.RelativeTimeFormat.format(-1, :day, locale: :en, numeric: :always)
{:ok, "1 day ago"}

@spec format!(integer(), atom(), Keyword.t()) :: String.t() | no_return()

Formats a relative time value, raising on error.

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

Arguments

• value is an integer offset.

• unit is the time unit atom.

• options is a keyword list of options.

Returns

• A formatted string.

Examples

iex> Intl.RelativeTimeFormat.format!(-1, :day, locale: :en)
"yesterday"

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

Formats a relative time value into typed parts.

Modelled on the JS Intl.RelativeTimeFormat.formatToParts(). Named forms ("yesterday") are a single :literal part; numeric forms tag the number as an :integer part carrying a :unit key, with the surrounding pattern text as :literal parts.

Arguments

• value is an integer offset.

• unit is the time unit atom.

• options is a keyword list of options. Accepts the same options as format/3.

Returns

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

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

Examples

iex> Intl.RelativeTimeFormat.format_to_parts(-1, :day, locale: :en)
{:ok, [%{type: :literal, value: "yesterday"}]}

iex> Intl.RelativeTimeFormat.format_to_parts(-3, :day, locale: :en)
{:ok, [
  %{type: :integer, value: "3", unit: :day},
  %{type: :literal, value: " days ago"}
]}

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

Formats a relative time value into typed parts, raising on error.

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

Arguments

• value is an integer offset.

• unit is the time unit atom.

• options is a keyword list of options.

Returns

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

Examples

iex> Intl.RelativeTimeFormat.format_to_parts!(-1, :day, locale: :en)
[%{type: :literal, value: "yesterday"}]