@spec ago(date_time_ish()) :: t()

Returns the duration between datetime and now, in the largest possible unit.

datetime can be an ISO8601-formatted string, a DateTime, or a NaiveDateTime.

See also from_now/1.

iex> DateTime.utc_now()
...> |> Moar.DateTime.subtract({121, :minute})
...> |> Moar.Duration.ago()
...> |> Moar.Duration.shift(:minute)
{121, :minute}

@spec approx(t()) :: t()

Shifts duration to an approximately equal duration that's simpler. For example, {121, :second} would get shifted to {2, :minute}.

Warning

This function is lossy because it intentionally loses precision.

If the time value of the duration is exactly 1, the duration is returned unchanged: {1, :minute} => {1, :minute}. Otherwise, the duration is shifted to the highest unit where the time value is >= 2.

iex> Moar.Duration.approx({1, :minute})
{1, :minute}

iex> Moar.Duration.approx({7300, :second})
{2, :hour}

@spec between(date_time_ish(), date_time_ish()) :: t()

Returns the duration between earlier and later, in the largest possible unit.

earlier and later can be ISO8601-formatted strings, DateTimes, or NaiveDateTimes.

iex> earlier = ~U[2020-01-01T00:00:00.000000Z]
iex> later = ~U[2020-01-01T02:01:00.000000Z]
iex> Moar.Duration.between(earlier, later)
{121, :minute}

@spec convert(from :: t(), to :: time_unit()) :: number()

Converts a {duration, time_unit} tuple into a numeric duration, rounding down to the nearest whole number.

Warning

This function is lossy because it rounds down to the nearest whole number.

Uses System.convert_time_unit/3 under the hood; see its documentation for more details.

It is similar to shift/1 but this function returns an integer value, while shift/1 returns a duration tuple.

iex> Moar.Duration.convert({121, :second}, :minute)
2

@spec format(
  t() | date_time_ish(),
  format_style() | format_transformers() | binary() | nil,
  format_transformers() | binary() | nil,
  binary() | nil
) :: binary()

Formats a duration in either a long or short style, with optional transformers and an optional suffix.

• The first argument is a duration tuple, unless one of the transformers is :ago, in which case it can be a DateTime, NaiveDateTime, or an ISO8601-formatted string.
• The second argument is optional and is the style, transformer, list of transformers, or suffix.
• The third argument is optional and is the transformer, list of transformers, or suffix.
• The fourth argument is optional and is the suffix.

Styles:

• :long, which formats like "25 seconds".
• :short, which formats like "25s".
• Defaults to :long

Transformers:

• :ago transforms via ago/1
• :approx transforms via approx/1
• :humanize transforms via humanize/1
• If no transformers are specified, no transformations are applied.

Suffix:

• A string that will be appended to the formatted result.
• If the :ago transformer is specified and a suffix is not specified, the suffix will default to "ago". To use the "ago" transformer with no suffix, specify an empty string as the suffix (nil will not suffice).

iex> Moar.Duration.format({1, :second})
"1 second"

iex> Moar.Duration.format({120, :second})
"120 seconds"

iex> Moar.Duration.format({120, :second}, :long)
"120 seconds"

iex> Moar.Duration.format({120, :second}, :short)
"120s"

iex> Moar.Duration.format({120, :second}, "yonder")
"120 seconds yonder"

iex> Moar.Duration.format({120, :second}, :humanize)
"2 minutes"

iex> Moar.Duration.format({120, :second}, :humanize, "yonder")
"2 minutes yonder"

iex> Moar.Duration.format({310, :second})
"310 seconds"

iex> Moar.Duration.format({310, :second}, :approx)
"5 minutes"

iex> DateTime.utc_now()
...> |> Moar.DateTime.add({-310, :second})
...> |> Moar.Duration.format(:short, [:ago, :approx], "henceforth")
"5m henceforth"

@spec from_now(date_time_ish()) :: t()

Returns the duration between now and datetime, in the largest possible unit.

datetime can be an ISO8601-formatted string, a DateTime, or a NaiveDateTime.

See also ago/1.

iex> DateTime.utc_now()
...> |> Moar.DateTime.add({121, :minute})
...> |> Moar.Duration.from_now()
...> |> Moar.Duration.approx()
{2, :hour}

@spec humanize(t()) :: t()

If possible, shifts duration to a higher time unit that is more readable to a human. Returns duration unchanged if it cannot be exactly shifted.

iex> Moar.Duration.humanize({60000, :millisecond})
{1, :minute}

iex> Moar.Duration.humanize({48, :hour})
{2, :day}

iex> Moar.Duration.humanize({49, :hour})
{49, :hour}

@spec shift(t(), time_unit()) :: t()

Shifts duration to time_unit. It is similar to convert/1 but this function returns a duration tuple, while convert/1 just returns an integer value.

Warning

This function is lossy because it rounds down to the nearest whole number.

iex> Moar.Duration.shift({121, :second}, :minute)
{2, :minute}

@spec shift_down(t()) :: t()

Shifts duration to the next smaller unit. Raises if it's already at the smallest unit (nanosecond).

iex> Moar.Duration.shift_down({1, :hour})
{60, :minute}

Shifts duration to the next larger unit. Raises if it's already at the largest unit (approx_year). Rounds the result towards zero.

Warning

This function is lossy because it rounds down to the nearest whole number.

iex> Moar.Duration.shift_up({60, :minute})
{1, :hour}

iex> Moar.Duration.shift_up({125, :minute})
{2, :hour}

@spec to_string(t()) :: String.t()

Shortcut to format(duration, :long). See format/4.