Convenience functions for range subsets

Intended for use in i in [.data.table.

between is equivalent to lower<=x & x<=upper when incbounds=TRUE, or lower<x & y<upper when FALSE. With a caveat that NA in lower or upper are taken as unlimited bounds not NA. This can be changed by setting NAbounds to NA.

inrange checks whether each value in x is in between any of the intervals provided in lower,upper.

Usage

between(x, lower, upper, incbounds=TRUE, NAbounds=TRUE, check=FALSE, ignore_tzone=FALSE)
x %between% y

inrange(x, lower, upper, incbounds=TRUE)
x %inrange% y

Arguments

x: Any orderable vector, i.e., those with relevant methods for `<=`, such as numeric, character, Date, etc. in case of between and a numeric vector in case of inrange.
lower: Lower range bound. Either length 1 or same length as x.
upper: Upper range bound. Either length 1 or same length as x.
y: A length-2 vector or list, with y[[1]] interpreted as lower and y[[2]] as upper.
incbounds: TRUE means inclusive bounds, i.e., [lower,upper]. FALSE means exclusive bounds, i.e., (lower,upper). It is set to TRUE by default for infix notations.
NAbounds: If lower (upper) contains an NA what should lower<=x (x<=upper) return? By default TRUE so that a missing bound is interpreted as unlimited.
check: Produce error if any(lower>upper)? FALSE by default for efficiency, in particular type character.
ignore_tzone: TRUE means skip timezone checks among x, lower, and upper.

Details

non-equi joins were implemented in v1.9.8. They extend binary search based joins in data.table to other binary operators including >=, <=, >, <. inrange makes use of this new functionality and performs a range join.

Value

Logical vector the same length as x with value TRUE for those that lie within the specified range.

Note

Current implementation does not make use of ordered keys for %between%.

Examples

X = data.table(a=1:5, b=6:10, c=c(5:1))
X[b %between% c(7,9)]
#>        a     b     c
#>    <int> <int> <int>
#> 1:     2     7     4
#> 2:     3     8     3
#> 3:     4     9     2
X[between(b, 7, 9)] # same as above
#>        a     b     c
#>    <int> <int> <int>
#> 1:     2     7     4
#> 2:     3     8     3
#> 3:     4     9     2
# NEW feature in v1.9.8, vectorised between
X[c %between% list(a,b)]
#>        a     b     c
#>    <int> <int> <int>
#> 1:     1     6     5
#> 2:     2     7     4
#> 3:     3     8     3
X[between(c, a, b)] # same as above
#>        a     b     c
#>    <int> <int> <int>
#> 1:     1     6     5
#> 2:     2     7     4
#> 3:     3     8     3
X[between(c, a, b, incbounds=FALSE)] # open interval
#>        a     b     c
#>    <int> <int> <int>
#> 1:     1     6     5
#> 2:     2     7     4

# inrange()
Y = data.table(a=c(8,3,10,7,-10), val=runif(5))
range = data.table(start = 1:5, end = 6:10)
Y[a %inrange% range]
#>        a       val
#>    <num>     <num>
#> 1:     8 0.6830724
#> 2:     3 0.3182244
#> 3:    10 0.1347508
#> 4:     7 0.9432908
Y[inrange(a, range$start, range$end)] # same as above
#>        a       val
#>    <num>     <num>
#> 1:     8 0.6830724
#> 2:     3 0.3182244
#> 3:    10 0.1347508
#> 4:     7 0.9432908
Y[inrange(a, range$start, range$end, incbounds=FALSE)] # open interval
#>        a       val
#>    <num>     <num>
#> 1:     8 0.6830724
#> 2:     3 0.3182244
#> 3:     7 0.9432908