Create an interval vector

• iv() creates an interval vector from start and end vectors. This is how you will typically create interval vectors, and is often used with columns in a data frame.

• iv_pairs() creates an interval vector from pairs. This is often useful for interactive testing, as it provides a more intuitive interface for creating small interval vectors. It should generally not be used on a large scale because it can be slow.

Intervals

Interval vectors are right-open, i.e. [start, end). This means that start < end is a requirement to generate an interval vector. In particular, empty intervals with start == end are not allowed.

Right-open intervals tend to be the most practically useful. For example, [2019-01-01 00:00:00, 2019-01-02 00:00:00) nicely encapsulates all times on 2019-01-01. With closed intervals, you'd have to attempt to specify this as 2019-01-01 23:59:59, which is inconvenient and inaccurate, as it doesn't capture fractional seconds.

Right-open intervals also have the extremely nice technical property that they create a closed algebra. Concretely, the complement of a vector of right-open intervals and the union, intersection, or difference of two vectors of right-open intervals will always result in another vector of right-open intervals.

Missing intervals

When creating interval vectors with iv(), if either bound is incomplete, then both bounds are set to their missing value.

Usage

iv(start, end, ..., ptype = NULL, size = NULL)

iv_pairs(..., ptype = NULL)

Arguments

start, end

[vector]

A pair of vectors to represent the bounds of the intervals.

To be a valid interval vector, start must be strictly less than end.

If either start or end are incomplete / missing, then both bounds will be coerced to missing values.

start and end are recycled against each other and are cast to the same type.

...

For iv_pairs():

[vector pairs]

Vectors of size 2 representing intervals to include in the result.

All inputs will be cast to the same type.

For iv():

These dots are for future extensions and must be empty.

ptype

[vector(0) / NULL]

A prototype to force for the inner type of the resulting iv. If NULL, this defaults to the common type of the inputs.

size

[integer(1) / NULL]

A size to force for the resulting iv. If NULL, this defaults to the common size of the inputs.

Value

An iv.

Examples

library(dplyr, warn.conflicts = FALSE)

set.seed(123)

x <- tibble(
  start = as.Date("2019-01-01") + 1:5,
  end = start + sample(1:10, length(start), replace = TRUE)
)

# Typically you'll use `iv()` with columns of a data frame
mutate(x, iv = iv(start, end), .keep = "unused")
#> # A tibble: 5 × 1
#>                         iv
#>                 <iv<date>>
#> 1 [2019-01-02, 2019-01-05)
#> 2 [2019-01-03, 2019-01-06)
#> 3 [2019-01-04, 2019-01-14)
#> 4 [2019-01-05, 2019-01-07)
#> 5 [2019-01-06, 2019-01-12)

# `iv_pairs()` is useful for generating interval vectors interactively
iv_pairs(c(1, 5), c(2, 3), c(6, 10))
#> <iv<double>[3]>
#> [1] [1, 5)  [2, 3)  [6, 10)