@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_parts(integer() | Date.t() | DateTime.t() | Time.t(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, Exception.t()}

Formats a relative time into typed parts, mirroring ECMA-402's formatToParts for Intl.RelativeTimeFormat.

The parts concatenate to exactly the string to_string/2 produces with the same options. Named forms ("yesterday") are a single :literal part; pattern forms tag the number as an :integer part carrying a :unit key ("3 days ago" is :integer "3" plus :literal " days ago"), matching the JS part shape.

Arguments

• relative is an integer, float, Date, Time, DateTime, or NaiveDateTime.

• options is a keyword list of options.

Options

See to_string/2 for the supported options.

Returns

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

• {:error, exception} if the options are invalid.

Examples

iex> Localize.DateTime.Relative.to_parts(-1, unit: :day, locale: :en)
{:ok, [%{type: :literal, value: "yesterday"}]}

iex> Localize.DateTime.Relative.to_parts(-3, unit: :day, locale: :en)
{:ok,
 [
   %{type: :integer, value: "3", unit: :day},
   %{type: :literal, value: " days ago"}
 ]}

iex> Localize.DateTime.Relative.to_parts(1, unit: :day, locale: :en, numeric: :always)
{:ok,
 [
   %{type: :literal, value: "in "},
   %{type: :integer, value: "1", unit: :day},
   %{type: :literal, value: " day"}
 ]}

@spec to_parts!(integer() | Date.t() | DateTime.t() | Time.t(), Keyword.t()) :: [
  %{type: atom(), value: String.t()}
]

Same as to_parts/2 but raises on error.

Arguments

• relative is an integer, float, Date, Time, DateTime, or NaiveDateTime.

• options is a keyword list of options. See to_parts/2.

Returns

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

Raises

• Raises an exception if the options are invalid.

Examples

iex> Localize.DateTime.Relative.to_parts!(-1, unit: :day, locale: :en)
[%{type: :literal, value: "yesterday"}]

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