Tempus (Tempus v0.3.0)

Documentation for Tempus.

Summary

Functions

Adds an amount of units to the origin, considering slots given.

Returns the reversed list of free days after origin.

Returns the reversed list of free days after origin.

Returns the reversed list of free days after origin.

Checks whether the slot is disjoined against slots.

Returns the next busy slot from the slots passed as a first argument, that immediately follows origin. IOf slots are overlapped, the overlapped one gets returned.

Returns the next free slot from the slots passed as a first argument, that immediately follows origin. If slots are overlapped, the overlapped one gets returned.

Types

count()

Specs

count() :: :infinity | :stream | non_neg_integer()

direction()

Specs

direction() :: :fwd | :bwd

option()

Specs

option() ::
  {:origin, Tempus.Slot.origin()}
  | {:count, count() | neg_integer()}
  | {:direction, direction()}

options()

Specs

options() :: [option()]

Functions

add(slots, origin \\ DateTime.utc_now(), amount_to_add, unit \\ :second)

Specs

add(
  slots :: Tempus.Slots.t(),
  origin :: DateTime.t(),
  amount_to_add :: integer(),
  unit :: System.time_unit()
) :: DateTime.t()

Adds an amount of units to the origin, considering slots given.

days_add(slots, opts \\ [])

(since 0.2.0)

Specs

days_add(slots :: Tempus.Slots.t(), opts :: options()) :: Date.t()

Returns the reversed list of free days after origin.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.days_add(slots, origin: ~D|2020-08-07|, count: 3) |> hd()
~D|2020-08-12|
iex> Tempus.days_add(slots, origin: ~D|2020-08-07|, count: 3, direction: :fwd) |> hd()
~D|2020-08-12|
iex> Tempus.days_add(slots, origin: ~D|2020-08-07|, count: -3, direction: :bwd) |> hd()
~D|2020-08-12|
iex> Tempus.days_add(slots, origin: ~D|2020-08-12|, count: -4) |> hd()
~D|2020-08-06|
iex> Tempus.days_add(slots, origin: ~D|2020-08-12|, count: 4, direction: :bwd) |> hd()
~D|2020-08-06|
iex> Tempus.days_add(slots, origin: ~D|2020-08-12|, count: -4, direction: :fwd) |> hd()
~D|2020-08-06|

days_ago(slots, origin, count)

This function is deprecated. Use days_add/2 with negative count or `:bwd` forth parameter instead.

Specs

days_ago(slots :: Tempus.Slots.t(), origin :: Date.t(), count :: integer()) ::
  Date.t()

Returns the reversed list of free days after origin.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.days_ago(slots, ~D|2020-08-07|, 0)
[~D|2020-08-06|]
iex> Tempus.days_ago(slots, ~D|2020-08-12|, 4) |> hd()
~D|2020-08-06|

days_ahead(slots, origin, count)

This function is deprecated. Use days_add/2 instead.

Specs

days_ahead(slots :: Tempus.Slots.t(), origin :: Date.t(), count :: integer()) ::
  Date.t()

Returns the reversed list of free days after origin.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.days_ahead(slots, ~D|2020-08-07|, 0)
[~D|2020-08-08|]
iex> Tempus.days_ahead(slots, ~D|2020-08-07|, 3) |> hd()
~D|2020-08-12|

free?(slots, slot)

Specs

free?(slots :: Tempus.Slots.t(), slot :: Tempus.Slot.origin()) ::
  boolean() | no_return()

Checks whether the slot is disjoined against slots.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.free?(slots, ~D|2020-08-07|)
false
iex> Tempus.free?(slots, ~D|2020-08-08|)
true

next_busy(slots, opts \\ [])

Specs

next_busy(Tempus.Slots.t(), options()) ::
  [Tempus.Slot.t()] | Tempus.Slot.t() | nil | no_return()

Returns the next busy slot from the slots passed as a first argument, that immediately follows origin. IOf slots are overlapped, the overlapped one gets returned.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-08 23:00:00Z|, to: ~U|2020-08-09 12:00:00Z|})
#Slot<[from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-07 11:00:00Z|, to: ~U|2020-08-07 12:00:00Z|}, count: 2) |> hd()
#Slot<[from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-07 11:00:00Z|, to: ~U|2020-08-08 12:00:00Z|})
#Slot<[from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-07 11:00:00Z|, to: ~U|2020-08-10 12:00:00Z|})
#Slot<[from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: ~D|2020-08-07|)
#Slot<[from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: ~D|2020-08-08|)
#Slot<[from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: ~D|2020-08-08|, direction: :bwd)
#Slot<[from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: ~D|2020-08-10|, direction: :bwd)
#Slot<[from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]]>
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-11 11:00:00Z|, to: ~U|2020-08-11 12:00:00Z|})
nil
iex> Tempus.next_busy(slots, origin: %Tempus.Slot{from: ~U|2020-08-06 11:00:00Z|, to: ~U|2020-08-06 12:00:00Z|}, direction: :bwd)
nil
iex> Tempus.next_busy(%Tempus.Slots{})
nil

next_free(slots, opts \\ [])

Specs

Returns the next free slot from the slots passed as a first argument, that immediately follows origin. If slots are overlapped, the overlapped one gets returned.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|),
...>   Tempus.Slot.wrap(~D|2020-08-12|),
...>   Tempus.Slot.wrap(~D|2020-08-14|)
...> ] |> Enum.into(%Tempus.Slots{})
iex> Tempus.next_free(slots, origin: %Tempus.Slot{from: ~U|2020-08-08 23:00:00Z|, to: ~U|2020-08-09 12:00:00Z|})
#Slot<[from: ~U[2020-08-08 00:00:00.000000Z], to: ~U[2020-08-09 23:59:59.999999Z]]>
iex> Tempus.next_free(slots, origin: %Tempus.Slot{from: ~U|2020-08-06 11:00:00Z|, to: ~U|2020-08-06 12:00:00Z|})
#Slot<[from: ~U[2020-08-06 11:00:00.000000Z], to: ~U[2020-08-06 23:59:59.999999Z]]>
iex> Tempus.next_free(slots, origin: ~U|2020-08-13 01:00:00.000000Z|)
#Slot<[from: ~U[2020-08-13 00:00:00.000000Z], to: ~U[2020-08-13 23:59:59.999999Z]]>
iex> Tempus.next_free(slots, origin: ~D|2020-08-13|)
#Slot<[from: ~U[2020-08-13 00:00:00.000000Z], to: ~U[2020-08-13 23:59:59.999999Z]]>
iex> Tempus.next_free(slots, origin: ~D|2020-08-14|)
#Slot<[from: ~U[2020-08-15 00:00:00.000000Z], to: nil]>
iex> Tempus.next_free(slots, origin: ~D|2020-08-07|, count: 5)
[
  %Tempus.Slot{from: ~U[2020-08-08 00:00:00.000000Z], to: ~U[2020-08-09 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-11 00:00:00.000000Z], to: ~U[2020-08-11 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-13 00:00:00.000000Z], to: ~U[2020-08-13 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-15 00:00:00.000000Z], to: nil}
]
iex> Tempus.next_free(slots, origin: ~D|2020-08-15|, count: -5)
[
  %Tempus.Slot{from: ~U[2020-08-15 00:00:00.000000Z], to: ~U[2020-08-15 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-13 00:00:00.000000Z], to: ~U[2020-08-13 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-11 00:00:00.000000Z], to: ~U[2020-08-11 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-08 00:00:00.000000Z], to: ~U[2020-08-09 23:59:59.999999Z]},
  %Tempus.Slot{from: nil, to: ~U[2020-08-06 23:59:59.999999Z]},
]
iex> Tempus.next_free(slots, origin: ~D|2020-08-12|, count: :infinity, direction: :bwd)
[
  %Tempus.Slot{from: ~U[2020-08-11 00:00:00.000000Z], to: ~U[2020-08-11 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-08 00:00:00.000000Z], to: ~U[2020-08-09 23:59:59.999999Z]},
  %Tempus.Slot{from: nil, to: ~U[2020-08-06 23:59:59.999999Z]}
]