These helpers provide a means of standardizing common indexing methods such as integer, character or logical indexing.
vec_as_location() accepts integer, character, or logical vectors
of any size. The output is always an integer vector that is
suitable for subsetting with [ or vec_slice(). It might be a
different size than the input because negative selections are
transformed to positive ones and logical vectors are transformed
to a vector of indices for the TRUE locations.
vec_as_location2() accepts a single number or string. It returns
a single location as a integer vector of size 1. This is suitable
for extracting with [[.
num_as_location() and num_as_location2() are specialized variants
that have extra options for numeric indices.
vec_as_location(
i,
n,
names = NULL,
...,
missing = c("propagate", "remove", "error"),
arg = caller_arg(i),
call = caller_env()
)
num_as_location(
i,
n,
...,
missing = c("propagate", "remove", "error"),
negative = c("invert", "error", "ignore"),
oob = c("error", "remove", "extend"),
zero = c("remove", "error", "ignore"),
arg = caller_arg(i),
call = caller_env()
)
vec_as_location2(
i,
n,
names = NULL,
...,
missing = c("error", "propagate"),
arg = caller_arg(i),
call = caller_env()
)
num_as_location2(
i,
n,
...,
negative = c("error", "ignore"),
missing = c("error", "propagate"),
arg = caller_arg(i),
call = caller_env()
)An integer, character or logical vector specifying the
locations or names of the observations to get/set. Specify
TRUE to index all elements (as in x[]), or NULL, FALSE or
integer() to index none (as in x[NULL]).
A single integer representing the total size of the
object that i is meant to index into.
If i is a character vector, names should be a character
vector that i will be matched against to construct the index. Otherwise,
not used. The default value of NULL will result in an error
if i is a character vector.
These dots are for future extensions and must be empty.
How should missing i values be handled?
"error" throws an error.
"propagate" returns them as is.
"remove" removes them.
By default, vector subscripts propagate missing values but scalar subscripts error on them.
Propagated missing values can't be combined with negative indices when
negative = "invert", because they can't be meaningfully inverted.
The argument name to be displayed in error messages.
The execution environment of a currently
running function, e.g. caller_env(). The function will be
mentioned in error messages as the source of the error. See the
call argument of abort() for more information.
How should negative i values be handled?
"error" throws an error.
"ignore" returns them as is.
"invert" returns the positive location generated by inverting the
negative location. When inverting, positive and negative locations
can't be mixed. This option is only applicable for num_as_location().
How should out-of-bounds i values be handled?
"error" throws an error.
"remove" removes both positive and negative out-of-bounds locations.
"extend" allows positive out-of-bounds locations if they directly
follow the end of a vector. This can be used to implement extendable
vectors, like letters[1:30].
How should zero i values be handled?
"error" throws an error.
"remove" removes them.
"ignore" returns them as is.
vec_as_location() and num_as_location() return an integer vector that
can be used as an index in a subsetting operation.
vec_as_location2() and num_as_location2() return an integer of size 1
that can be used a scalar index for extracting an element.
x <- array(1:6, c(2, 3))
dimnames(x) <- list(c("r1", "r2"), c("c1", "c2", "c3"))
# The most common use case validates row indices
vec_as_location(1, vec_size(x))
#> [1] 1
# Negative indices can be used to index from the back
vec_as_location(-1, vec_size(x))
#> [1] 2
# Character vectors can be used if `names` are provided
vec_as_location("r2", vec_size(x), rownames(x))
#> [1] 2
# You can also construct an index for dimensions other than the first
vec_as_location(c("c2", "c1"), ncol(x), colnames(x))
#> [1] 2 1