calendar_interval v0.2.0 CalendarInterval behaviour View Source

Functions for working with calendar intervals.

Types

Relation between two intervals according to Allen's Interval Algebra

Functions

Returns interval that encloses given interval

Returns first element of the interval

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

Returns last element of the interval

Returns an interval within given interval

Returns an interval starting at given date truncated to `precision`

Returns next interval

Parses a string into an interval

Returns previous interval

Returns a `relation` between `interval1` and `interval2`

Handles the `~I` sigil for intervals

Splits interval by another interval

Returns string representation

Returns an union of `interval1` and `interval2` or `nil`

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

Callbacks

Calendar callback that adds years and months to a naive datetime

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
|``````

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``````

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

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``````

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

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``````

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

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

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

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

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``````

sigil_I(arg, list) View Source (macro)

Handles the `~I` sigil for intervals.

Examples

``````iex> ~I"2018-06".precision
:month``````

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

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

Returns string representation.

Examples

``````iex> CalendarInterval.to_string(~I"2018-06")
"2018-06"``````

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``````

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``````

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()}```
`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`.