@spec contains?(t(), t()) :: boolean()

Returns true if the first interval includes every point in time the second includes.

examples

Examples

iex> Elixir.Timex.Interval.contains?(Elixir.Timex.Interval.new(from: ~D[2018-01-01], until: ~D[2018-01-31]), Elixir.Timex.Interval.new(from: ~D[2018-01-01], until: ~D[2018-01-30]))
true

iex> Elixir.Timex.Interval.contains?(Elixir.Timex.Interval.new(from: ~D[2018-01-01], until: ~D[2018-01-30]), Elixir.Timex.Interval.new(from: ~D[2018-01-01], until: ~D[2018-01-31]))
false

iex> Elixir.Timex.Interval.contains?(Elixir.Timex.Interval.new(from: ~D[2018-01-01], until: ~D[2018-01-10]), Elixir.Timex.Interval.new(from: ~D[2018-01-05], until: ~D[2018-01-15]))
false

@spec difference(t(), t()) :: [t()]

Removes one interval from another which may reduce, split, or eliminate the original interval. Returns a (possibly empty) list of intervals representing the remaining time.

graphs

Graphs

The following textual graphs show all the ways that the original interval and the removal can relate to each other, and the action that difference/2 will take in each case. The original interval is drawn with Os and the removal interval with Xs.

# return original
OO
    XX

# trim end
OOO
  XXX

# trim end
OOOOO
  XXX

# split
OOOOOOO
  XXX

# eliminate
OO
XX

# eliminate
OO
XXXX

# trim beginning
OOOO
XX

# eliminate
  OO
XXXXXX

# eliminate
    OO
XXXXXX

# trim beginning
  OOO
XXX

# return original
     OO
XX

examples

Examples

iex> Elixir.Timex.Interval.difference(Elixir.Timex.Interval.new(from: ~N[2018-01-01 02:00:00.000], until: ~N[2018-01-01 04:00:00.000]), Elixir.Timex.Interval.new(from: ~N[2018-01-01 03:00:00.000], until: ~N[2018-01-01 05:00:00.000]))
[%Elixir.Timex.Interval{from: ~N[2018-01-01 02:00:00.000], left_open: false, right_open: true, step: [days: 1], until: ~N[2018-01-01 03:00:00.000]}]

iex> Elixir.Timex.Interval.difference(Elixir.Timex.Interval.new(from: ~N[2018-01-01 01:00:00.000], until: ~N[2018-01-01 05:00:00.000]), Elixir.Timex.Interval.new(from: ~N[2018-01-01 02:00:00.000], until: ~N[2018-01-01 03:00:00.000]))
[%Elixir.Timex.Interval{from: ~N[2018-01-01 01:00:00.000], left_open: false, right_open: true, step: [days: 1], until: ~N[2018-01-01 02:00:00.000]}, %Elixir.Timex.Interval{from: ~N[2018-01-01 03:00:00.000], left_open: false, right_open: true, step: [days: 1], until: ~N[2018-01-01 05:00:00.000]}]

iex> Elixir.Timex.Interval.difference(Elixir.Timex.Interval.new(from: ~N[2018-01-01 02:00:00.000], until: ~N[2018-01-01 04:00:00.000]), Elixir.Timex.Interval.new(from: ~N[2018-01-01 01:00:00.000], until: ~N[2018-01-01 05:00:00.000]))
[]

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

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)

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

Formats the interval as a human readable string.

examples

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)"

@spec new(Keyword.t()) :: t() | {:error, :invalid_until} | {:error, :invalid_step}

Create a new Interval struct.

Note: By default intervals are left closed, i.e. they include the from date/time, and exclude the until date/time. Put another way, from <= x < until. This behavior matches that of other popular date/time libraries, such as Joda Time, as well as the SQL behavior of the overlaps keyword.

Options:

• from: The date the interval starts at. Should be a (Naive)DateTime.
• until: Either a (Naive)DateTime, or a time shift that will be applied to the from date. This value must be greater than from, otherwise an error will be returned.
• 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 terms left_open and right_open come from the mathematical concept of intervals. You can see more detail on the theory on Wikipedia, but it can be more intuitively thought of like so:

• An "open" bound is exclusive, and a "closed" bound is inclusive
• So a left-closed interval includes the from value, and a left-open interval does not.
• Likewise, a right-closed interval includes the until value, and a right-open interval does not.
• An open interval is both left and right open, conversely, a closed interval is both left and right closed.

Note: until shifts delegate to Timex.shift, so the options provided should match its valid options.

examples

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]"

@spec overlaps?(t(), t()) :: boolean()

Returns true if the first interval shares any point(s) in time with the second.

examples

Examples

iex> Elixir.Timex.Interval.overlaps?(Elixir.Timex.Interval.new(from: ~D[2016-03-04], until: [days: 1]), Elixir.Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]))
true

iex> Elixir.Timex.Interval.overlaps?(Elixir.Timex.Interval.new(from: ~D[2016-03-07], until: [days: 1]), Elixir.Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3]))
false

@spec with_step(t(), valid_interval_steps()) :: 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

Examples

iex> use Timex
...> Interval.new(from: ~D[2014-09-22], until: [days: 3], right_open: true)
...> |> Interval.with_step([days: 1]) |> Enum.map(&Timex.format!(&1, "%Y-%m-%d", :strftime))
["2014-09-22", "2014-09-23", "2014-09-24"]

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"]