@spec add(DateTime.t(), Moar.Duration.t()) :: DateTime.t()

Adds duration to date_time.

See also subtract/1 and Moar.NaiveDateTime.add/2.

Note

This function is naive and intentionally doesn't account for real-world calendars and all of their complexity, such as leap years, leap days, daylight saving time, past and future calendar oddities, etc.

As "Falsehoods programmers believe about time" says, "If you think you understand everything about time, you're probably doing it wrong."

See Cldr.Calendar.plus/2 for one example of a function that is far more likely to be correct.

iex> start = ~U[2022-01-01T00:00:00.000Z]
iex> Moar.DateTime.add(start, {3, :minute})
~U[2022-01-01T00:03:00.000Z]

@spec between?(
  DateTime.t(),
  {DateTime.t(), DateTime.t()}
) :: boolean()

Returns true if date_time is inclusively inside range which is a tuple containing a start datetime and an end datetime.

iex> Moar.DateTime.between?(~U[2022-01-01T02:00:00Z], {~U[2022-01-01T01:00:00Z], ~U[2022-01-01T03:00:00Z]})
true

iex> Moar.DateTime.between?(~U[2022-01-01T04:00:00Z], {~U[2022-01-01T01:00:00Z], ~U[2022-01-01T03:00:00Z]})
false

@spec from_iso8601!(date_time_string :: String.t()) :: DateTime.t()

Like DateTime.from_iso8601/1 but raises if the string cannot be parsed.

iex> Moar.DateTime.from_iso8601!("2022-01-01T00:00:00Z")
~U[2022-01-01T00:00:00Z]

iex> Moar.DateTime.from_iso8601!("2022-01-01T00:00:00+0800")
** (ArgumentError) Expected "2022-01-01T00:00:00+0800" to have a UTC offset of 0, but was: 28800

iex> Moar.DateTime.from_iso8601!("Next Thursday after lunch")
** (ArgumentError) Invalid ISO8601 format: "Next Thursday after lunch"

@spec recent?(DateTime.t(), Moar.Duration.t() | nil) :: boolean()

Returns true if date_time is now or in the past and no older than duration ago (which defaults to 1 minute). Returns false if date_time is in the future.

iex> Moar.DateTime.recent?(Moar.DateTime.utc_now(minus: {30, :second}))
true

iex> Moar.DateTime.recent?(Moar.DateTime.utc_now(minus: {5, :minute}))
false

iex> Moar.DateTime.recent?(Moar.DateTime.utc_now(minus: {5, :minute}), {1, :hour})
true

iex> Moar.DateTime.recent?(Moar.DateTime.utc_now(plus: {5, :second}))
false

@spec subtract(DateTime.t(), Moar.Duration.t()) :: DateTime.t()

Subtracts duration from date_time.

See also add/1 and Moar.NaiveDateTime.subtract/2.

Note

This function is naive and intentionally doesn't account for real-world calendars and all of their complexity, such as leap years, leap days, daylight saving time, past and future calendar oddities, etc.

As "Falsehoods programmers believe about time" says, "If you think you understand everything about time, you're probably doing it wrong."

See Cldr.Calendar.minus/4 for one example of a function that is far more likely to be correct.

iex> start = ~U[2022-01-01T00:03:00.000Z]
iex> Moar.DateTime.subtract(start, {3, :minute})
~U[2022-01-01T00:00:00.000Z]

@spec to_iso8601_rounded(date_time :: DateTime.t()) :: String.t()

Like DateTime.to_iso8601/1 but rounds to the nearest second first.

iex> Moar.DateTime.to_iso8601_rounded(~U[2022-01-01T01:02:03.456789Z])
"2022-01-01T01:02:03Z"

@spec utc_now([{:plus, Moar.Duration.t()}] | [{:minus, Moar.Duration.t()}]) ::
  DateTime.t()

Returns the current UTC time plus or minus the given duration.

iex> Moar.DateTime.utc_now(plus: {10500, :millisecond})
...> |> Moar.Duration.format([:approx, :from_now])
"10 seconds from now"

iex> Moar.DateTime.utc_now(minus: {10, :second})
...> |> Moar.Duration.format([:approx, :ago])
"10 seconds ago"

@spec within?(DateTime.t(), Moar.Duration.t() | nil) :: boolean()

Returns true if date_time is no older than duration ago, and no later than duration from now.

iex> Moar.DateTime.within?(Moar.DateTime.utc_now(minus: {30, :second}), {1, :minute})
true

iex> Moar.DateTime.within?(Moar.DateTime.utc_now(plus: {30, :second}), {1, :minute})
true

iex> Moar.DateTime.within?(Moar.DateTime.utc_now(minus: {5, :minute}), {1, :minute})
false

iex> Moar.DateTime.within?(Moar.DateTime.utc_now(plus: {5, :minute}), {1, :minute})
false