calendar_interval

v0.2.0

calendar_interval v0.2.0 CalendarInterval behaviour View Source

Functions for working with calendar intervals.

Link to this section Summary

Types

precision()
relation()

Relation between two intervals according to Allen's Interval Algebra

t()

Functions

enclosing(interval, new_precision)

Returns interval that encloses given interval

first(calendar_interval)

Returns first element of the interval

intersection(interval1, interval2)

Returns an intersection of interval1 and interval2 or nil if they don't overlap

last(calendar_interval)

Returns last element of the interval

nest(interval, new_precision)

Returns an interval within given interval

new(naive_datetime, precision)

Returns an interval starting at given date truncated to precision

next(interval, step \\ 1)

Returns next interval

parse!(string)

Parses a string into an interval

prev(interval, step \\ 1)

Returns previous interval

relation(interval1, interval2)

Returns a relation between interval1 and interval2

sigil_I(arg, list)

Handles the ~I sigil for intervals

split(interval1, interval2)

Splits interval by another interval

to_string(calendar_interval)

Returns string representation

union(interval1, interval2)

Returns an union of interval1 and interval2 or nil

utc_now(precision \\ {:microsecond, 6})

Returns an interval for the current UTC time in given precision/0

Callbacks

add(arg1, arg2, arg3, arg4, arg5, arg6, arg7, precision, step)

Calendar callback that adds years and months to a naive datetime

Link to this section Types

Link to this type

precision() View Source 
precision() ::
  :year | :month | :day | :hour | :minute | :second | {:microsecond, 1..6}

Link to this type

relation() View Source 
relation() ::
  :equal
  | :meets
  | :met_by
  | :preceds
  | :preceded_by
  | :starts
  | :started_by
  | :finishes
  | :finished_by
  | :during
  | :contains
  | :overlaps
  | :overlapped_by

Relation between two intervals according to Allen's Interval Algebra.

                  |
a preceds b       | aaaa
                  |       bbbb
-------------------------------
                  |
a meets b         | aaaa
                  |     bbbb
                  |
-------------------------------
                  |
a overlaps b      | aaaa
                  |   bbbb
                  |
-------------------------------
                  |
a finished by b   | aaaa
                  |   bb
                  |
-------------------------------
                  |
a contains b      | aaaaaa
                  |   bb
                  |
-------------------------------
                  |
a starts b        |  aa
                  |  bbbb
                  |
-------------------------------
                  |
a equals b        | aaaa
                  | bbbb
                  |
-------------------------------
                  |
a started by b    | aaaa
                  | bb
                  |
-------------------------------
                  |
a during b        |   aa
                  | bbbbbb
                  |
-------------------------------
                  |
a finishes b      |   aa
                  | bbbb
                  |
-------------------------------
                  |
a overlapped by b |   aaaa
                  | bbbb
                  |
-------------------------------
                  |
a met by b        |     aaaa
                  | bbbb
                  |
-------------------------------
                  |
a preceded by b   |       aaaa
                  | bbbb
                  |

See: https://www.ics.uci.edu/~alspaugh/cls/shr/allen.html

Link to this type

t() View Source 
t() :: %CalendarInterval{
  first: NaiveDateTime.t(),
  last: NaiveDateTime.t(),
  precision: precision()
}

Link to this section Functions

Link to this function

enclosing(interval, new_precision) View Source 
enclosing(t(), precision()) :: t()

Returns interval that encloses given interval.

Example 

iex> CalendarInterval.enclosing(~I"2018-05-01", :year)
~I"2018"

iex> CalendarInterval.enclosing(~I"2018-06-15", :second)
** (ArgumentError) cannot enclose from :day to :second
Link to this function

first(calendar_interval) View Source 
first(t()) :: t()

Returns first element of the interval.

Examples 

iex> CalendarInterval.first(~I"2018-01/12")
~I"2018-01"

iex> CalendarInterval.first(~I"2018-01")
~I"2018-01"
Link to this function

intersection(interval1, interval2) View Source 
intersection(t(), t()) :: t() | nil

Returns an intersection of interval1 and interval2 or nil if they don't overlap.

Both intervals must have the same precision.

Examples 

iex> CalendarInterval.intersection(~I"2018-01/04", ~I"2018-03/06")
~I"2018-03/04"
iex> CalendarInterval.intersection(~I"2018-01/12", ~I"2018-02")
~I"2018-02"

iex> CalendarInterval.intersection(~I"2018-01/02", ~I"2018-11/12")
nil
Link to this function

last(calendar_interval) View Source 
last(t()) :: t()

Returns last element of the interval.

Examples 

iex> CalendarInterval.last(~I"2018-01/12")
~I"2018-12"

iex> CalendarInterval.last(~I"2018-01")
~I"2018-01"
Link to this function

nest(interval, new_precision) View Source 
nest(t(), precision()) :: t()

Returns an interval within given interval.

Example 

iex> CalendarInterval.nest(~I"2018", :day)
~I"2018-01-01/12-31"

iex> CalendarInterval.nest(~I"2018-06-15", :minute)
~I"2018-06-15 00:00/23:59"

iex> CalendarInterval.nest(~I"2018-06-15", :year)
** (ArgumentError) cannot nest from :day to :year
Link to this function

new(naive_datetime, precision) View Source 
new(NaiveDateTime.t() | Date.t(), precision()) :: t()

Returns an interval starting at given date truncated to precision.

Examples 

iex> CalendarInterval.new(~N"2018-06-15 10:20:30.134", :minute)
~I"2018-06-15 10:20"

iex> CalendarInterval.new(~D"2018-06-15", :minute)
~I"2018-06-15 00:00"
Link to this function

next(interval, step \\ 1) View Source 
next(t(), step :: integer()) :: t()

Returns next interval.

Examples 

iex> CalendarInterval.next(~I"2018-06-30")
~I"2018-07-01"
iex> CalendarInterval.next(~I"2018-06-30 09:00", 80)
~I"2018-06-30 10:20"

iex> CalendarInterval.next(~I"2018-01/06")
~I"2018-07/12"
iex> CalendarInterval.next(~I"2018-01/02", 2)
~I"2018-05/06"
Link to this function

parse!(string) View Source 
parse!(String.t()) :: t()

Parses a string into an interval.

Examples 

iex> CalendarInterval.parse!("2018-06-30")
~I"2018-06-30"

iex> CalendarInterval.parse!("2018-06-01/30")
~I"2018-06-01/30"
Link to this function

prev(interval, step \\ 1) View Source 
prev(t(), step :: integer()) :: t()

Returns previous interval.

Examples 

iex> CalendarInterval.prev(~I"2018-06-01")
~I"2018-05-31"
iex> CalendarInterval.prev(~I"2018-06-01 01:00", 80)
~I"2018-05-31 23:40"

iex> CalendarInterval.prev(~I"2018-07/12")
~I"2018-01/06"
iex> CalendarInterval.prev(~I"2018-05/06", 2)
~I"2018-01/02"
Link to this function

relation(interval1, interval2) View Source 
relation(t(), t()) :: relation()

Returns a relation between interval1 and interval2.

Examples 

iex> CalendarInterval.relation(~I"2018-01/02", ~I"2018-06")
:preceds

iex> CalendarInterval.relation(~I"2018-01/02", ~I"2018-03")
:meets

iex> CalendarInterval.relation(~I"2018-02", ~I"2018-01/12")
:during
Link to this macro

sigil_I(arg, list) View Source (macro)

Handles the ~I sigil for intervals.

Examples 

iex> ~I"2018-06".precision
:month
Link to this function

split(interval1, interval2) View Source 
split(t(), t()) :: t() | {t(), t()} | {t(), t(), t()}

Splits interval by another interval.

Examples 

iex> CalendarInterval.split(~I"2018-01/12", ~I"2018-04/05")
{~I"2018-01/03", ~I"2018-04/05", ~I"2018-06/12"}

iex> CalendarInterval.split(~I"2018-01/12", ~I"2018-01/02")
{~I"2018-01/02", ~I"2018-03/12"}
iex> CalendarInterval.split(~I"2018-01/12", ~I"2018-08/12")
{~I"2018-01/07", ~I"2018-08/12"}

iex> CalendarInterval.split(~I"2018-01/12", ~I"2019-01")
~I"2018-01/12"
Link to this function

to_string(calendar_interval) View Source 
to_string(t()) :: String.t()

Returns string representation.

Examples 

iex> CalendarInterval.to_string(~I"2018-06")
"2018-06"
Link to this function

union(interval1, interval2) View Source 
union(t(), t()) :: t() | nil

Returns an union of interval1 and interval2 or nil.

Both intervals must have the same precision.

Examples 

iex> CalendarInterval.union(~I"2018-01/02", ~I"2018-01/04")
~I"2018-01/04"
iex> CalendarInterval.union(~I"2018-01/11", ~I"2018-12")
~I"2018-01/12"

iex> CalendarInterval.union(~I"2018-01/02", ~I"2018-04/05")
nil
Link to this function

utc_now(precision \\ {:microsecond, 6}) View Source 
utc_now(precision()) :: t()

Returns an interval for the current UTC time in given precision/0.

Examples 

iex> CalendarInterval.utc_now(:month) in ~I"2018/2100"
true

Link to this section Callbacks

Link to this callback

add(arg1, arg2, arg3, arg4, arg5, arg6, arg7, precision, step) View Source 
add(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond(),
  precision(),
  step :: integer()
) :: {Calendar.year(), Calendar.month(), Calendar.day()}

Calendar callback that adds years and months to a naive datetime.

step can be positive or negative.

When streaming intervals, this is the callback that increments years and months. Incrementing other time precision is managed directly through NaiveDateTime.add/3.