# `Localize.DateTime.Relative`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.0/lib/localize/datetime/relative.ex#L1)

Formats relative time strings such as "3 days ago", "tomorrow",
or "in 10 seconds".

Supports integer offsets (in seconds), `Date`, `DateTime`,
`NaiveDateTime`, and `Time` structs.

# `known_units`

```elixir
@spec known_units() :: [atom(), ...]
```

Returns the list of known time units.

# `to_string`

```elixir
@spec to_string(integer() | Date.t() | DateTime.t() | Time.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns a string representing a relative time for a given
number, date, time, or datetime.

### Arguments

* `relative` is an integer (seconds from now), or a `Date`,
  `DateTime`, `NaiveDateTime`, or `Time` struct.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is `:en`.

* `:format` is `:standard`, `:narrow`, or `:short`.
  The default is `:standard`.

* `:unit` is the time unit for formatting. One of `:second`,
  `:minute`, `:hour`, `:day`, `:week`, `:month`, `:year`,
  `:mon`, `:tue`, `:wed`, `:thu`, `:fri`, `:sat`, `:sun`,
  `:quarter`. If omitted, a unit is derived automatically.

* `:relative_to` is the baseline date/datetime from which
  the difference is calculated. Defaults to now.

### Returns

* `{:ok, formatted_string}` on success.

* `{:error, exception}` on failure.

### Examples

    iex> Localize.DateTime.Relative.to_string(-1, unit: :day, locale: :en)
    {:ok, "yesterday"}

    iex> Localize.DateTime.Relative.to_string(1, unit: :day, locale: :en)
    {:ok, "tomorrow"}

    iex> Localize.DateTime.Relative.to_string(-3, unit: :day, locale: :en)
    {:ok, "3 days ago"}

    iex> Localize.DateTime.Relative.to_string(2, unit: :hour, locale: :en)
    {:ok, "in 2 hours"}

# `to_string!`

```elixir
@spec to_string!(integer() | Date.t() | DateTime.t() | Time.t(), Keyword.t()) ::
  String.t()
```

Same as `to_string/2` but raises on error.

---

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