View Source Moar.DateTime (Moar v1.18.1)
DateTime-related functions. See also Moar.NaiveDateTime
.
Link to this section Summary
Functions
Adds duration
to date_time
.
Like DateTime.from_iso8601/1
but raises if the string cannot be parsed.
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
@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:00Z]
@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 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:00Z]
@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"