Skip to content

Create a vector of locations

Source: R/subscript-loc.R
vec_as_location.Rd

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