vec_as_location: Create a vector of locations

Description Usage Arguments Value Examples

View source: R/subscript-loc.R

Description

These helpers provide a means of standardizing common indexing methods such as integer, character or logical indexing.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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 April 29, 2021, 5:08 p.m.