This family of functions detects different types of relationships between
two ivs. It works similar to base::%in%, where `needles[i]`

checks for
a relationship in all of `haystack`

.

`iv_overlaps()`

detects a specific`type`

of overlap between the two ivs.`iv_precedes()`

detects if`needles[i]`

precedes (i.e. comes before) any interval in`haystack`

.`iv_follows()`

detects if`needles[i]`

follows (i.e. comes after) any interval in`haystack`

.

These functions return a logical vector the same size as `needles`

containing
`TRUE`

if the interval in `needles`

has a matching relationship in
`haystack`

and `FALSE`

otherwise.

## Usage

```
iv_overlaps(needles, haystack, ..., type = "any", missing = "equals")
iv_precedes(needles, haystack, ..., missing = "equals")
iv_follows(needles, haystack, ..., missing = "equals")
```

## Arguments

- needles, haystack
`[iv]`

Interval vectors used for relation matching.

Each element of

`needles`

represents the interval to search for.`haystack`

represents the intervals to search in.

Prior to comparison,

`needles`

and`haystack`

are coerced to the same type.- ...
These dots are for future extensions and must be empty.

- type
`[character(1)]`

The type of relationship to find. One of:

`"any"`

: Finds any overlap whatsoever between an interval in`needles`

and an interval in`haystack`

.`"within"`

: Finds when an interval in`needles`

is completely within (or equal to) an interval in`haystack`

.`"contains"`

: Finds when an interval in`needles`

completely contains (or equals) an interval in`haystack`

.`"equals"`

: Finds when an interval in`needles`

is exactly equal to an interval in`haystack`

.`"starts"`

: Finds when the start of an interval in`needles`

matches the start of an interval in`haystack`

.`"ends"`

: Finds when the end of an interval in`needles`

matches the end of an interval in`haystack`

.

- missing
`[logical(1) / "equals" / "error"]`

Handling of missing intervals in

`needles`

.`"equals"`

considers missing intervals in`needles`

as exactly equal to missing intervals in`haystack`

when determining if there is a matching relationship between them. Matched missing intervals in`needles`

result in a`TRUE`

value in the result, and unmatched missing intervals result in a`FALSE`

value.`"error"`

throws an error if any intervals in`needles`

are missing.If a single logical value is provided, this represents the value returned in the result for intervals in

`needles`

that are missing. You can force missing intervals to be unmatched by setting this to`FALSE`

, and you can force them to be propagated by setting this to`NA`

.

## Examples

```
library(vctrs)
x <- iv_pairs(
as.Date(c("2019-01-05", "2019-01-10")),
as.Date(c("2019-01-07", "2019-01-15")),
as.Date(c("2019-01-20", "2019-01-31"))
)
y <- iv_pairs(
as.Date(c("2019-01-01", "2019-01-03")),
as.Date(c("2019-01-04", "2019-01-08")),
as.Date(c("2019-01-07", "2019-01-09")),
as.Date(c("2019-01-10", "2019-01-20")),
as.Date(c("2019-01-15", "2019-01-20"))
)
x
#> <iv<date>[3]>
#> [1] [2019-01-05, 2019-01-10) [2019-01-07, 2019-01-15) [2019-01-20, 2019-01-31)
y
#> <iv<date>[5]>
#> [1] [2019-01-01, 2019-01-03) [2019-01-04, 2019-01-08) [2019-01-07, 2019-01-09)
#> [4] [2019-01-10, 2019-01-20) [2019-01-15, 2019-01-20)
# Does each interval of `x` overlap `y` at all?
iv_overlaps(x, y)
#> [1] TRUE TRUE FALSE
# Which intervals of `y` are within an interval in `x`?
iv_overlaps(y, x, type = "within")
#> [1] FALSE FALSE TRUE FALSE FALSE
# ---------------------------------------------------------------------------
a <- iv(c(1, NA), c(2, NA))
b <- iv(c(NA, NA), c(NA, NA))
# Missing intervals are seen as exactly equal by default, so they are
# considered to overlap
iv_overlaps(a, b)
#> [1] FALSE TRUE
# If you'd like missing intervals to be treated as unmatched, set
# `missing = FALSE`
iv_overlaps(a, b, missing = FALSE)
#> [1] FALSE FALSE
# If you'd like to propagate missing intervals, set `missing = NA`
iv_overlaps(a, b, missing = NA)
#> [1] FALSE NA
```