vctrs (version 0.6.5)

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

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.

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.

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