vec_slice: Get or set observations in a vector

In vctrs: Vector Helpers

Get or set observations in a vector

Description

This provides a common interface to extracting and modifying observations for all vector types, regardless of dimensionality. It is an analog to [ that matches vec_size() instead of length().

Usage

vec_slice(x, i, ..., error_call = current_env())

vec_slice(x, i) <- value

vec_assign(x, i, value, ..., x_arg = "", value_arg = "")

Arguments

x	A vector
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]).
...	These dots are for future extensions and must be empty.
error_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.
value	Replacement values. value is cast to the type of x, but only if they have a common type. See below for examples of this rule.
x_arg, value_arg	Argument names for x and value. These are used in error messages to inform the user about the locations of incompatible types and sizes (see stop_incompatible_type() and stop_incompatible_size()).

Value

A vector of the same type as x.

Genericity

Support for S3 objects depends on whether the object implements a vec_proxy() method.

• When a vec_proxy() method exists, the proxy is sliced and vec_restore() is called on the result.

• Otherwise vec_slice() falls back to the base generic [.

Note that S3 lists are treated as scalars by default, and will cause an error if they don't implement a vec_proxy() method.

Differences with base R subsetting

• vec_slice() only slices along one dimension. For two-dimensional types, the first dimension is subsetted.

• vec_slice() preserves attributes by default.

• ⁠vec_slice<-()⁠ is type-stable and always returns the same type as the LHS.

Dependencies

vctrs dependencies

• vec_proxy()

• vec_restore()

base dependencies

• base::`[`

If a non-data-frame vector class doesn't have a vec_proxy() method, the vector is sliced with [ instead.

Examples

x <- sample(10)
x
vec_slice(x, 1:3)

# You can assign with the infix variant:
vec_slice(x, 2) <- 100
x

# Or with the regular variant that doesn't modify the original input:
y <- vec_assign(x, 3, 500)
y
x


# Slicing objects of higher dimension:
vec_slice(mtcars, 1:3)

# Type stability --------------------------------------------------

# The assign variant is type stable. It always returns the same
# type as the input.
x <- 1:5
vec_slice(x, 2) <- 20.0

# `x` is still an integer vector because the RHS was cast to the
# type of the LHS:
vec_ptype(x)

# Compare to `[<-`:
x[2] <- 20.0
vec_ptype(x)


# Note that the types must be coercible for the cast to happen.
# For instance, you can cast a double vector of whole numbers to an
# integer vector:
vec_cast(1, integer())

# But not fractional doubles:
try(vec_cast(1.5, integer()))

# For this reason you can't assign fractional values in an integer
# vector:
x <- 1:3
try(vec_slice(x, 2) <- 1.5)

vctrs documentation built on May 29, 2024, 11:39 a.m.