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

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 type t() View Source
t() :: %Timex.Interval{
  from: term(),
  left_open: term(),
  right_open: term(),
  step: term(),
  until: term()
}
Link to this type valid_interval_step() View Source
valid_interval_step() ::
  [{:microseconds, integer()}]
  | [{:milliseconds, integer()}]
  | [{:seconds, integer()}]
  | [{:minutes, integer()}]
  | [{:hours, integer()}]
  | [{:days, integer()}]
  | [{:weeks, integer()}]
  | [{:months, integer()}]
  | [{:year, integer()}]

Link to this section Functions

Link to this function duration(interval, unit) View Source

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)
Link to this function format(interval, format, formatter \\ nil) View Source

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)"
Link to this function format!(interval, format, formatter \\ nil) View Source

Same as format/3, but raises a Timex.Interval.FormatError on failure.

Link to this function new(options \\ []) View Source
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 the from 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]"
Link to this function overlaps?(interval_a, interval_b) View Source

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
Link to this function with_step(interval, step) View Source
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"]