R: Create a vector of locations

vec_as_location {vctrs} | R Documentation

## 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"),
      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.
`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]`.

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

[Package vctrs version 0.2.2 Index]