View Source Moar.DateTime (Moar v1.32.0)

DateTime-related functions. See also Moar.NaiveDateTime.

Link to this section Summary

Functions

Adds duration to date_time.

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

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

Returns true if date_time is no older than duration ago (which defaults to 1 minute).

Subtracts duration from date_time.

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

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

Link to this section Functions

Link to this function

add(date_time, duration)

View Source
@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:00Z]
iex> Moar.DateTime.add(start, {3, :minute})
~U[2022-01-01T00:03:00.000Z]
Link to this function

between?(date_time, range)

View Source
@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
Link to this function

from_iso8601!(date_time_string)

View Source
@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"
Link to this function

recent?(date_time, duration \\ {1, :minute})

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

Returns true if date_time is no older than duration ago (which defaults to 1 minute).

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
Link to this function

subtract(date_time, duration)

View Source
@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:00Z]
iex> Moar.DateTime.subtract(start, {3, :minute})
~U[2022-01-01T00:00:00.000Z]
Link to this function

to_iso8601_rounded(date)

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