Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free
Documentation
R
vctrs

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

Usage

vec_as_location(
  i,
  n,
  names = NULL,
  ...,
  missing = c("propagate", "error"),
  arg = NULL
)

num_as_location(
  i,
  n,
  ...,
  missing = c("propagate", "error"),
  negative = c("invert", "error", "ignore"),
  oob = c("error", "extend"),
  zero = c("remove", "error", "ignore"),
  arg = NULL
)

vec_as_location2(
  i,
  n,
  names = NULL,
  ...,
  missing = c("error", "propagate"),
  arg = NULL
)

num_as_location2(
  i,
  n,
  ...,
  negative = c("error", "ignore"),
  missing = c("error", "propagate"),
  arg = NULL
)

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

Whether to throw an "error" when i is a missing value, or "propagate" it (return it as is). By default, vector subscripts can contain missing values and scalar subscripts can't.
arg

The argument name to be displayed in error messages when vec_as_location() and vec_as_location2() are used to check the type of a function input.
negative

Whether to throw an "error" when i is a negative location value, or "ignore" it.
oob

If "error", throws an informative "error" if some elements are out-of-bounds. If "extend", out-of-bounds locations are allowed if they are consecutive after the end. This can be used to implement extendable vectors like letters[1:30].
zero

Whether to "remove" zero values, throw an informative "error", or "ignore" them.

Value

vec_as_location() returns an integer vector that can be used as an index in a subsetting operation. vec_as_location2() returns 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

Vector Helpers

v0.3.8
MIT + file LICENSE
Authors
Hadley Wickham [aut], Lionel Henry [aut, cre], Davis Vaughan [aut], data.table team [cph] (Radix sort based on data.table's forder() and their contribution to R's order()), RStudio [cph]
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.