R: Convenience functions for range subsets.

between {data.table} | R Documentation

## Convenience functions for range subsets.

### Description

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

`between` is equivalent to `x >= lower & x <= upper` when `incbounds=TRUE`, or `x > lower & y < upper` when `FALSE`.

`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)
    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.
`upper` | Upper range bound.
`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.

### Details

From `v1.9.8+`, `between` is vectorised. `lower` and `upper` are recycled to `length(x)` if necessary.

non-equi joins were recently implemented in `v1.9.8`. It extends 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 as 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%`.

### See Also

`data.table`, `like`, `%chin%`

### Examples

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

    # 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]
    Y[inrange(a, range$start, range$end)] # same as above
    Y[inrange(a, range$start, range$end, incbounds=FALSE)] # open interval

[Package data.table version 1.11.8 Index]