iv {ivs}

Create an interval vector

Description

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

# `iv_pairs()` is useful for generating interval vectors interactively
iv_pairs(c(1, 5), c(2, 3), c(6, 10))