timex v3.2.0 Timex.Interval View Source
This module is used for creating and manipulating DateTime intervals.
Examples
iex> Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]) %Timex.Interval{from: ~N[2016-03-03 00:00:00], left_open: false, right_open: true, step: [days: 1], until: ~N[2016-03-06 00:00:00]}
iex> Timex.Interval.new(from: ~D[2016-03-03], until: ~N[2016-03-10 01:23:45]) %Timex.Interval{from: ~N[2016-03-03 00:00:00], left_open: false, right_open: true, step: [days: 1], until: ~N[2016-03-10 01:23:45]}
iex> ~N[2016-03-04 12:34:56] in Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]) true
iex> ~D[2016-03-01] in Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]) false
iex> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-01], until: [days: 5]), Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3])) true
iex> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-01], until: [days: 1]), Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3])) false
Link to this section Summary
Functions
Return the interval duration, given a unit
Formats the interval as a human readable string
Same as format/3
, but raises a Timex.Interval.FormatError
on failure
Create a new Interval struct
Returns true if the first interval shares any point(s) in time with the second
Change the step value for the provided interval
Link to this section Types
Link to this section Functions
Return the interval duration, given a unit.
When the unit is one of :seconds
, :minutes
, :hours
, :days
, :weeks
, :months
, :years
, the result is an integer
.
When the unit is :duration
, the result is a Duration
struct.
Example
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [months: 5])
...> |> Interval.duration(:months)
5
iex> use Timex
...> Interval.new(from: ~N[2014-09-22T15:30:00], until: [minutes: 20])
...> |> Interval.duration(:duration)
Duration.from_minutes(20)
Formats the interval as a human readable string.
Examples
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3])
...> |> Interval.format!("%Y-%m-%d %H:%M", :strftime)
"[2014-09-22 00:00, 2014-09-25 00:00)"
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3])
...> |> Interval.format!("%Y-%m-%d", :strftime)
"[2014-09-22, 2014-09-25)"
Same as format/3
, but raises a Timex.Interval.FormatError
on failure.
new(Keyword.t()) :: Interval.t() | {:error, :invalid_until} | {:error, :invalid_step}
Create a new Interval struct.
Note: By default intervals are right open.
Valid keywords:
from
: The date the interval starts at. Should be a DateTime.until
: Either a DateTime, or a time shift that will be applied to thefrom
date.left_open
: Whether the interval is left open. See explanation below.right_open
: Whether the interval is right open. See explanation below.step
: The step to use when iterating the interval, defaults to[days: 1]
The termsleft_open
and right_open
come from the mathematical concept of intervals, the following
excerpt from Wikipedia gives a good explanation of their meaning:
"An interval is said to be left-open if and only if it has no minimum
(an element that is smaller than all other elements); right-open if it has no maximum;
and open if it has both properties. The interval [0,1) = {x | 0 ≤ x < 1}, for example,
is left-closed and right-open. The empty set and the set of all reals are open intervals,
while the set of non-negative reals, for example, is a right-open but not left-open interval.
The open intervals coincide with the open sets of the real line in its standard topology."
Note: until
shifts delegate to Timex.shift
, so the options provided should match its valid options.
Examples
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: ~D[2014-09-29])
...> |> Interval.format!("%Y-%m-%d", :strftime)
"[2014-09-22, 2014-09-29)"
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 7])
...> |> Interval.format!("%Y-%m-%d", :strftime)
"[2014-09-22, 2014-09-29)"
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 7], left_open: true, right_open: false)
...> |> Interval.format!("%Y-%m-%d", :strftime)
"(2014-09-22, 2014-09-29]"
iex> use Timex
...> Interval.new(from: ~N[2014-09-22T15:30:00], until: [minutes: 20], right_open: false)
...> |> Interval.format!("%H:%M", :strftime)
"[15:30, 15:50]"
overlaps?(Timex.Interval.t(), Timex.Interval.t()) :: boolean()
Returns true if the first interval shares any point(s) in time with the second.
Examples
iex> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-04], until: [days: 1]), Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]))
true
iex> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-07], until: [days: 1]), Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]))
false
with_step(Interval.t(), any()) :: Interval.t() | {:error, :invalid_step}
Change the step value for the provided interval.
The step should be a keyword list valid for use with Timex.Date.shift
.
Examples
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3], right_open: false)
...> |> Interval.with_step([days: 1]) |> Enum.map(&Timex.format!(&1, "%Y-%m-%d", :strftime))
["2014-09-22", "2014-09-23", "2014-09-24", "2014-09-25"]
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3], right_open: false)
...> |> Interval.with_step([days: 2]) |> Enum.map(&Timex.format!(&1, "%Y-%m-%d", :strftime))
["2014-09-22", "2014-09-24"]
iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3], right_open: false)
...> |> Interval.with_step([days: 3]) |> Enum.map(&Timex.format!(&1, "%Y-%m-%d", :strftime))
["2014-09-22", "2014-09-25"]