vec_as_location: Create a vector of locations

In vctrs: Vector Helpers

Create a vector of locations

Description

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.

Usage

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()
)

Arguments

i	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]).
n	A single integer representing the total size of the object that i is meant to index into.
names	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.
missing	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.
arg	The argument name to be displayed in error messages.
call	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.
negative	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().
oob	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].
zero	How should zero i values be handled? "error" throws an error. "remove" removes them. "ignore" returns them as is.

Value

• 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.

Examples

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

# Negative indices can be used to index from the back
vec_as_location(-1, vec_size(x))

# Character vectors can be used if `names` are provided
vec_as_location("r2", vec_size(x), rownames(x))

# You can also construct an index for dimensions other than the first
vec_as_location(c("c2", "c1"), ncol(x), colnames(x))

vctrs documentation built on Oct. 13, 2023, 1:05 a.m.