Tempus.Slot (Tempus v0.3.0)

Wraps the argument into a slot. For DateTime it’d be a single microsecond. For a Date, it would be the whole day, starting at 00:00:00.000000 and

Types

origin()

Specs

origin() :: t() | Date.t() | DateTime.t() | Time.t() | nil

The origin used in comparisons and calculations

t()

Specs

t() :: %Tempus.Slot{from: nil | DateTime.t(), to: nil | DateTime.t()}

A timeslot to be used in Tempus

Functions

compare(s1, s2, strict \\ false)

Specs

compare(s1 :: t(), s2 :: t(), strict :: boolean()) :: :lt | :gt | :eq | :joint

Compares two slot structs.

Returns :gt if first slot is strictly later than the second and :lt for vice versa. NB :eq is returned not only if slots are equal, but also when they are overlapped.

Might be used in Enum.sort/2.

cover?(slot, dt, strict? \\ false)

Specs

cover?(slot :: t(), dt :: origin(), strict? :: boolean()) :: boolean()

Checks whether to Slot covers the data/datetime passed as a second argument.

Examples

iex> dt_between = ~U|2015-09-30 01:00:00Z|
...> dt_from = ~U|2015-09-30 00:00:00Z|
...> dt_to = ~U|2015-10-01 01:00:00Z|
...> d_from = Date.from_iso8601!("2015-09-30")
...> d_to = Date.from_iso8601!("2015-10-01")
iex> slot = %Tempus.Slot{from: dt_from, to: dt_to}
iex> Tempus.Slot.cover?(slot, dt_between)
true
iex> Tempus.Slot.cover?(slot, dt_to)
true
iex> Tempus.Slot.cover?(slot, dt_to, true)
false
iex> Tempus.Slot.cover?(slot, d_from)
true
iex> Tempus.Slot.cover?(slot, d_from, true)
false
iex> Tempus.Slot.cover?(slot, d_to)
false

disjoint?(s1, s2)

Specs

disjoint?(s1 :: origin(), s2 :: origin()) :: boolean()

Returns true if two slots are disjoined, false otherwise.

Examples

iex> slot = %Tempus.Slot{from: ~U|2015-09-01 00:00:00Z|, to: ~U|2015-10-01 00:00:00Z|}
iex> inner = %Tempus.Slot{from: ~U|2015-09-01 00:00:00Z|, to: ~U|2015-09-01 01:00:00Z|}
iex> Tempus.Slot.disjoint?(slot, inner)
false
iex> inner = %Tempus.Slot{from: ~U|2015-09-01 00:00:00Z|, to: ~U|2015-10-01 01:00:00Z|}
iex> Tempus.Slot.disjoint?(slot, inner)
false
iex> outer = %Tempus.Slot{from: ~U|2015-10-01 00:00:01Z|, to: ~U|2015-10-01 01:00:00Z|}
iex> Tempus.Slot.disjoint?(slot, outer)
true

duration(slot, unit \\ :second)

Specs

duration(slot :: t(), unit :: System.time_unit()) ::
  non_neg_integer() | :infinity

Calculates the duration of a slot in units given as a second parameter (default: :second.)

Example

iex> ~D|2020-09-03| |> Tempus.Slot.wrap() |> Tempus.Slot.duration()
86400

intersect(slots)

Specs

intersect(slots :: Enum.t()) :: t() | nil

Intersects slots to the minimal covered timeslice.

Example

iex> Tempus.Slot.intersect([Tempus.Slot.wrap(~D|2020-09-30|),
...>   %Tempus.Slot{from: ~U|2020-09-30 23:00:00Z|, to: ~U|2020-10-02 00:00:00Z|}])
#Slot<[from: ~U[2020-09-30 23:00:00Z], to: ~U[2020-09-30 23:59:59.999999Z]]>

join(slots)

Specs

join(slots :: Enum.t()) :: t()

Joins slots to the maximal covered timeslice.

Example

iex> Tempus.Slot.join([Tempus.Slot.wrap(~D|2020-09-30|), Tempus.Slot.wrap(~D|2020-10-02|)])
#Slot<[from: ~U[2020-09-30 00:00:00.000000Z], to: ~U[2020-10-02 23:59:59.999999Z]]>

shift_tz(slot, tz \\ "Etc/UTC", tz_db \\ Calendar.get_time_zone_database())

Specs

shift_tz(
  slot :: t(),
  tz :: Calendar.time_zone(),
  tz_db :: Calendar.time_zone_database()
) :: t()

Shifts both from and to values to UTC zone.

Examples

slot = %Tempus.Slot{
   from: DateTime.from_naive!(~N|2018-01-05 21:00:00|, "America/New_York"),
   to: DateTime.from_naive!(~N|2018-01-08 08:59:59|, "Australia/Sydney")
}
#⇒ #Slot<[from: ~U[2018-01-06 02:00:00Z], to: ~U[2018-01-07 21:59:59Z]]>

strict_compare(s1, s2)

Specs

strict_compare(s1 :: t(), s2 :: t()) :: :eq | :lt | :gt | :joint

Compares two slot structs. The same as compare/2, but returns :joint if the slots are overlapped.

valid?(arg1)

Specs

valid?(slot :: t()) :: boolean()

Checks whether the Slot is valid (to > from) or not.

Examples

iex> slot = %Tempus.Slot{from: ~U|2015-09-30 00:00:00Z|, to: ~U|2015-10-01 01:00:00Z|}
iex> Tempus.Slot.valid?(slot)
true
iex> Tempus.Slot.valid?(%Tempus.Slot{from: slot.to, to: slot.from})
false

wrap(moment, origin \\ DateTime.utc_now())

Specs

wrap(origin(), DateTime.t()) :: t()

Wraps the argument into a slot. For DateTime it’d be a single microsecond. For a Date, it would be the whole day, starting at 00:00:00.000000 and

ending at `23:59:59:999999`.

Examples

iex> Tempus.Slot.wrap(~D|2020-08-06|)
#Slot<[from: ~U[2020-08-06 00:00:00.000000Z], to: ~U[2020-08-06 23:59:59.999999Z]]>