Tox.Interval (tox v0.2.1)

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 by a combination of DateTime/DateTime, Datetime/Period or Period/DateTime.

The key boundaries specifies if the start and ending belongs 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

Functions

Returns the previous interval.

Returns the datetime on which the interval ends.

Creates a new interval or raises an error.

Returns the next interval.

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

Returns the datetime on which the interval starts.

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

Link to this section Types

Specs

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

Specs

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

Link to this section Functions

Link to this function

contains?(period, datetime)

Specs

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

Returns the previous interval.

The interval boundaries are not influence the returned datetime.

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
Link to this function

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>
Link to this function

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}
Link to this function

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[>

Specs

next(t()) :: t()

Returns the next interval.

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.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[>
Link to this function

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
Link to this function

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>
Link to this function

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