View Source Tempus.Slots (Tempus v0.15.0)

The interface to deal with the implementation of Tempus.Slot ordered collection.

Comes with several default implementations, backed up by ordered list of slots, by Stream, by AVLTree¹, and by Year-Month² tree.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|),
...>   %Tempus.Slot{
...>       from: ~U|2020-08-07 01:00:00Z|, to: ~U|2020-08-08 01:00:00Z|}]
...> Enum.into(slots, %Tempus.Slots{})
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-08 01:00:00Z]},
  %Tempus.Slot{from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]}]}}
iex> Enum.map(slots, & &1.from)
[~U[2020-08-07 00:00:00.000000Z], ~U[2020-08-10 00:00:00.000000Z], ~U[2020-08-07 01:00:00Z]]

Summary

Types

container()

implementation(group)

implementation(group, exact_implementation)

locator()

The type to use in navigation and/or rewinding slots enumerables

t()

t(group)

t(group, exact_implementation)

Functions

add(slots, slot, options \\ [])

Adds another slot to the slots collection.

count(slots)

Returns the number of slots

drop_until(slots, pivot, options \\ [])

inverse(slots, options \\ [])

Inverses Slots returning the new Slots instance with slots set where there were blanks.

merge(slots, enum \\ [], options \\ [])

Merges many slots into the first element in the list given as an argument.

new(implementation \\ Tempus.Slots.List, data)

Creates an instance of slots, using a backend given as a parameter.

span(slots, duration, unit \\ :second)

take_until(slots, pivot, options \\ [])

wrap(any, options \\ [])

Wraps the argument into a slots instance. For nil it’d be an empty slots. For everything else it’d call Slot.wrap/1 on an argument and add it to empty slots.

Types

container()

@type container() :: Enumerable.t(Tempus.Slot.t())

implementation(group)

@type implementation(group) :: implementation(group, container())

implementation(group, exact_implementation)

@type implementation(group, exact_implementation) :: %{
  __struct__: group,
  slots: exact_implementation
}

locator()

@type locator() ::
  Tempus.Slot.origin() | (Tempus.Slot.t() -> :gt | :eq | :lt | true | false)

The type to use in navigation and/or rewinding slots enumerables

t()

@type t() :: t(Tempus.Slots.Group.t())

t(group)

@type t(group) :: t(group, implementation(group))

t(group, exact_implementation)

@type t(group, exact_implementation) :: %Tempus.Slots{
  slots: implementation(group, exact_implementation)
}

Functions

add(slots, slot, options \\ [])

Adds another slot to the slots collection.

Joins slots intersecting with the new one, if any.

Example

iex> Tempus.Slots.add(%Tempus.Slots{}, Tempus.Slot.wrap(~D|2020-08-07|))
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]}]}}

iex> %Tempus.Slots{}
...> |> Tempus.Slots.add(Tempus.Slot.wrap(~D|2020-08-07|))
...> |> Tempus.Slots.add(Tempus.Slot.wrap(~D|2020-08-10|))
...> |> Tempus.Slots.add(%Tempus.Slot{
...>       from: ~U|2020-08-07 01:00:00Z|, to: ~U|2020-08-08 01:00:00Z|})
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-08 01:00:00Z]},
  %Tempus.Slot{from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]}]}}

count(slots)

@spec count(t()) :: non_neg_integer()

Returns the number of slots

Examples

iex> import Tempus.Sigils
iex> slots = [
...>   ~I(2000-01-01T00:00:00.000000Z → 2000-01-01T23:59:59.999999Z),
...>   ~I(2010-01-01T00:00:00.000000Z → 2010-01-01T23:59:59.999999Z),
...>   ~I(2020-01-01T00:00:00.000000Z → 2020-01-01T23:59:59.999999Z)
...> ]
iex> slots |> Tempus.Slots.new() |> Tempus.Slots.count()
3

drop_until(slots, pivot, options \\ [])

@spec drop_until(t(), locator(), keyword()) :: t()

inverse(slots, options \\ [])

@spec inverse(
  slots :: t(),
  keyword()
) :: t()

Inverses Slots returning the new Slots instance with slots set where there were blanks.

Example

iex> [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-08|),
...>   Tempus.Slot.wrap(~D|2020-08-10|),
...>   Tempus.Slot.wrap(~D|2020-08-12|)
...> ] |> Enum.into(%Tempus.Slots{})
...> |> Tempus.Slots.inverse()
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: nil, to: ~U[2020-08-06 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-09 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: nil}]}}

iex> [
...>   %Tempus.Slot{to: ~U[2020-08-08 23:59:59.999999Z]},
...>   Tempus.Slot.wrap(~D|2020-08-10|),
...>   %Tempus.Slot{from: ~U[2020-08-12 00:00:00.000000Z]}
...> ] |> Enum.into(%Tempus.Slots{})
...> |> Tempus.Slots.inverse()
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-09 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]}]}}

merge(slots, enum \\ [], options \\ [])

@spec merge(
  slots :: t() | [t()],
  Enumerable.t(Tempus.Slot.t()) | keyword(),
  keyword()
) :: t()

Merges many slots into the first element in the list given as an argument.

Other arguments might be enumerables, the first one must be a Tempus.Slots instance.

Examples

iex> slots = [
...>   Tempus.Slot.wrap(~D|2020-08-07|),
...>   Tempus.Slot.wrap(~D|2020-08-10|)
...> ] |> Enum.into(%Tempus.Slots{})
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-07 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]}]}}
iex> other = [
...>   %Tempus.Slot{from: ~U|2020-08-07 23:00:00Z|, to: ~U|2020-08-08 12:00:00Z|},
...>   %Tempus.Slot{from: ~U|2020-08-12 23:00:00Z|, to: ~U|2020-08-12 23:30:00Z|}
...> ]
iex> Tempus.Slots.merge([slots, other])
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-08 12:00:00Z]},
  %Tempus.Slot{from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]},
  %Tempus.Slot{from: ~U[2020-08-12 23:00:00Z], to: ~U[2020-08-12 23:30:00Z]}]}}
iex> Tempus.Slots.merge([slots, Tempus.Slots.wrap(other, Tempus.Slots.Stream)]) |> Enum.to_list()
[%Tempus.Slot{from: ~U[2020-08-07 00:00:00.000000Z], to: ~U[2020-08-08 12:00:00Z]},
 %Tempus.Slot{from: ~U[2020-08-10 00:00:00.000000Z], to: ~U[2020-08-10 23:59:59.999999Z]},
 %Tempus.Slot{from: ~U[2020-08-12 23:00:00Z], to: ~U[2020-08-12 23:30:00Z]}]

new(implementation \\ Tempus.Slots.List, data)

@spec new(implementation :: :list | :data | module(), data :: Enumerable.t()) :: t()

Creates an instance of slots, using a backend given as a parameter.

Examples

iex> import Tempus.Sigils
iex> slots = [
...>   ~I(2000-01-01T00:00:00.000000Z → 2000-01-01T23:59:59.999999Z),
...>   ~I(2010-01-01T00:00:00.000000Z → 2010-01-01T23:59:59.999999Z),
...>   ~I(2020-01-01T00:00:00.000000Z → 2020-01-01T23:59:59.999999Z)
...> ]
iex> Tempus.Slots.new([~D|2000-01-01|, ~D|2010-01-01|, ~D|2020-01-01|])
%Tempus.Slots{slots: Enum.into(slots, Tempus.Slots.List.new())}

span(slots, duration, unit \\ :second)

@spec span(t() | [Tempus.Slot.t()], non_neg_integer(), unit :: System.time_unit()) ::
  Enumerable.t()

take_until(slots, pivot, options \\ [])

@spec take_until(t(), locator(), keyword()) :: t()

wrap(any, options \\ [])

(since 0.3.0)

@spec wrap(
  [Tempus.Slot.origin()] | t(),
  keyword()
) :: t()

Wraps the argument into a slots instance. For nil it’d be an empty slots. For everything else it’d call Slot.wrap/1 on an argument and add it to empty slots.

Examples

iex> Tempus.Slots.wrap(~D|2020-08-06|)
%Tempus.Slots{slots: %Tempus.Slots.List{slots: [
  %Tempus.Slot{from: ~U[2020-08-06 00:00:00.000000Z], to: ~U[2020-08-06 23:59:59.999999Z]}]}}