Moar.DateTime (Moar v2.6.0)
View SourceDateTime-related functions. See also Moar.NaiveDateTime.
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 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.
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.
Returns true if date_time is no older than duration ago, and no later than duration from now.
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:00.000Z]
iex> Moar.DateTime.add(start, {3, :minute})
~U[2022-01-01T00:03:00.000Z]Makes a DateTime at a particular Time today, optionally shifting by a Duration.
iex> Moar.DateTime.at(~T[13:00:00])
DateTime.new!(Date.utc_today(), ~T[13:00:00])
iex> Moar.DateTime.at(~T[13:00:00], shift: [day: 2, hour: -3])
DateTime.new!(Date.utc_today(), ~T[10:00:00]) |> DateTime.add(2, :day)@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