Tox.Interval (tox v0.2.3)

An Interval struct and functions.

A time interval is the intervening time between two time points. The amount of intervening time is expressed by a combination of DateTime/DateTime, Datetime/Period or Period/DateTime.

The key boundaries indicates whether the start and the ending belong to the interval.

Valid values for boundaries are:

:open: start and ending are excluded
:closed: start and ending are included
:left_open: start is excluded and ending is included
:right_open: (default) start is included and ending is excluded

Examples

The default :right_open:

iex> datetime = DateTime.from_naive!(~N[2020-04-10 00:00:00], "America/Rainy_River")
iex> {:ok, interval} = Tox.Interval.new(
...>   datetime, Tox.Period.new!(day: 1)
...> )
iex> interval
#Tox.Interval<[2020-04-10T00:00:00-05:00/P1D[>
iex> Tox.Interval.contains?(interval, datetime)
true
iex> Tox.Interval.contains?(interval, Tox.DateTime.shift(datetime, day: 1))
false

With boundaries set to :open:

iex> datetime = DateTime.from_naive!(~N[2020-04-10 00:00:00], "America/Rainy_River")
iex> {:ok, interval} = Tox.Interval.new(
...>   datetime, Tox.Period.new!(day: 1), :open
...> )
iex> interval
#Tox.Interval<]2020-04-10T00:00:00-05:00/P1D[>
iex> Tox.Interval.contains?(interval, datetime)
false
iex> Tox.Interval.contains?(interval, Tox.DateTime.shift(datetime, day: 1))
false

With boundaries set to :left_open:

iex> datetime = DateTime.from_naive!(~N[2020-04-10 00:00:00], "America/Rainy_River")
iex> {:ok, interval} = Tox.Interval.new(
...>   datetime, Tox.Period.new!(day: 1), :left_open
...> )
iex> interval
#Tox.Interval<]2020-04-10T00:00:00-05:00/P1D]>
iex> Tox.Interval.contains?(interval, datetime)
false
iex> Tox.Interval.contains?(interval, Tox.DateTime.shift(datetime, day: 1))
true

With boundaries set to :closed:

iex> datetime = DateTime.from_naive!(~N[2020-04-10 00:00:00], "America/Rainy_River")
iex> {:ok, interval} = Tox.Interval.new(
...>   datetime, Tox.Period.new!(day: 1), :closed
...> )
iex> interval
#Tox.Interval<[2020-04-10T00:00:00-05:00/P1D]>
iex> Tox.Interval.contains?(interval, datetime)
true
iex> Tox.Interval.contains?(interval, Tox.DateTime.shift(datetime, day: 1))
true

Link to this section Summary

Types

boundary()

t()

Functions

contains?(interval, datetime)

Returns true when the datetime is in the given interval.

ending_datetime(map)

Returns the datetime on which the interval ends.

new(start, ending, boundaries \\ :right_open)

Creates a new interval.

new!(start, ending, boundaries \\ :right_open)

Creates a new interval or raises an error.

next(map)

Returns the next interval.

since_start(period, datetime, unit \\ :second)

Returns {:ok, amount} where amount is the time since the start of the interval.

start_datetime(map)

Returns the datetime on which the interval starts.

until_ending(period, datetime, unit \\ :second)

Returns {:ok, amount} where amount is the time until the ending of the interval.

Link to this section Types

boundary()

Specs

boundary() :: DateTime.t() | Tox.Period.t()

t()

Specs

t() :: %Tox.Interval{
  boundaries: Tox.boundaries(),
  ending: boundary(),
  start: boundary()
}

Link to this section Functions

contains?(interval, datetime)

Specs

contains?(t(), DateTime.t()) :: boolean()

Returns true when the datetime is in the given interval.

Whether the statrt and end belong to the interval is determined by the value for boundaries. See the documentation at the top.

Examples

iex> interval = Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-02-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
iex> datetime = DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin")
iex> Tox.Interval.contains?(interval, datetime)
false

ending_datetime(map)

Specs

ending_datetime(t()) :: DateTime.t()

Returns the datetime on which the interval ends.

The interval boundaries are not influence the returned datetime.

Examples

iex> interval = Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
iex> Tox.Interval.ending_datetime(interval)
#DateTime<2020-02-01 00:00:00+01:00 CET Europe/Berlin>

iex> interval = Tox.Interval.new!(
...>   Tox.Period.new!(month: 1),
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin")
...> )
iex> Tox.Interval.ending_datetime(interval)
#DateTime<2020-01-01 00:00:00+01:00 CET Europe/Berlin>

new(start, ending, boundaries \\ :right_open)

Specs

new(boundary(), boundary(), Tox.boundaries()) ::
  {:ok, t()} | {:error, :invalid_interval}

Creates a new interval.

See module documentation for more informations.

Examples

iex> {:ok, interval} = Tox.Interval.new(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
iex> interval
#Tox.Interval<[2020-01-01T00:00:00+01:00/P1M[>

iex> Tox.Interval.new(
...>   Tox.Period.new!(month: 1),
...>   Tox.Period.new!(month: 1)
...> )
{:error, :invalid_interval}

new!(start, ending, boundaries \\ :right_open)

Specs

new!(boundary(), boundary(), Tox.boundaries()) :: t()

Creates a new interval or raises an error.

See module documentation for more informations.

Examples

iex> Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
#Tox.Interval<[2020-01-01T00:00:00+01:00/P1M[>

next(map)

Specs

next(t()) :: t()

Returns the next interval.

Examples

iex> interval = Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
iex> Tox.Interval.next(interval)
#Tox.Interval<[2020-02-01T00:00:00+01:00/P1M[>

iex> interval = Tox.Interval.new!(
...>   Tox.Period.new!(month: 1),
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin")
...> )
iex> Tox.Interval.next(interval)
#Tox.Interval<[P1M/2020-02-01T00:00:00+01:00[>

iex> interval = Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   DateTime.from_naive!(~N[2020-01-02 00:00:00], "Europe/Berlin")
...> )
iex> Tox.Interval.next(interval)
#Tox.Interval<[2020-01-02T00:00:00+01:00/2020-01-03T00:00:00+01:00[>

since_start(period, datetime, unit \\ :second)

Specs

since_start(t(), DateTime.t(), System.time_unit()) :: {:ok, integer()} | :error

Returns {:ok, amount} where amount is the time since the start of the interval.

If the interval does not contains the given datetime an :error will be returned.

Examples

iex> now = DateTime.utc_now()
iex> interval =
...>   Tox.Interval.new!(
...>     Tox.DateTime.shift(now, hour: -1),
...>     Tox.Period.new!(hour: 2, minute: 10)
...>   )
iex> Tox.Interval.since_start(interval, now)
{:ok, 3600}
iex> Tox.Interval.since_start(interval, Tox.DateTime.shift(now, hour: 10))
:error

start_datetime(map)

Specs

start_datetime(t()) :: DateTime.t()

Returns the datetime on which the interval starts.

The interval boundaries are not influence the returned datetime.

Examples

iex> interval = Tox.Interval.new!(
...>   Tox.Period.new!(month: 1),
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin")
...> )
iex> Tox.Interval.start_datetime(interval)
#DateTime<2019-12-01 00:00:00+01:00 CET Europe/Berlin>

iex> interval = Tox.Interval.new!(
...>   DateTime.from_naive!(~N[2020-01-01 00:00:00], "Europe/Berlin"),
...>   Tox.Period.new!(month: 1)
...> )
iex> Tox.Interval.start_datetime(interval)
#DateTime<2020-01-01 00:00:00+01:00 CET Europe/Berlin>

until_ending(period, datetime, unit \\ :second)

Specs

until_ending(t(), DateTime.t(), System.time_unit()) :: {:ok, integer()} | :error

Returns {:ok, amount} where amount is the time until the ending of the interval.

If the interval does not contains the given datetime an :error will be returned.

Examples

iex> now = DateTime.utc_now()
iex> interval =
...>   Tox.Interval.new!(
...>     Tox.DateTime.shift(now, hour: -1),
...>     Tox.Period.new!(hour: 2, minute: 10)
...>   )
iex> Tox.Interval.until_ending(interval, now)
{:ok, 4200}
iex> Tox.Interval.until_ending(interval, Tox.DateTime.shift(now, hour: 10))
:error