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
andending
are excluded:closed
:start
andending
are included:left_open
:start
is excluded andending
is included:right_open
: (default)start
is included andending
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 true when the datetime
is in the given interval
.
Returns the datetime on which the interval ends.
Creates a new interval.
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
boundary()
Specs
boundary() :: DateTime.t() | Tox.Period.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
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