# `Intl.RelativeTimeFormat`
[🔗](https://github.com/elixir-localize/intl/blob/v1.1.0/lib/intl/relative_time_format.ex#L1)

Locale-sensitive relative time formatting, modelled on
[`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).

Produces strings such as "3 days ago", "in 2 hours", "yesterday",
or "tomorrow" depending on the value, unit, and locale.

Delegates to `Localize.DateTime.Relative` for the underlying
formatting.

# `format`

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

# `format!`

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

# `format_to_parts`

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

# `format_to_parts!`

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

---

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