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

Returns the list of known time units.

Examples

iex> Localize.DateTime.Relative.known_units()
[:day, :fri, :hour, :minute, :mon, :month, :quarter, :sat, :second, :sun, :thu, :tue, :wed, :week, :year]

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

• :numeric is :auto or :always, mirroring ECMA-402's numeric option. With :auto (the default), named forms such as "yesterday" and "tomorrow" are used when the locale defines them. With :always, output is always numeric: "1 day ago" instead of "yesterday".

• :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"}

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

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

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

Same as to_string/2 but raises on error.

Options

See to_string/2 for the supported options.

Examples

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

iex> Localize.DateTime.Relative.to_string!(~D[2024-06-14], relative_to: ~D[2024-06-15], locale: :en)
"yesterday"