vctrs (version 0.7.0)

vec_slice: 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. They are analogs to [ and [<- that match vec_size() instead of length().

Usage

vec_slice(x, i, ..., error_call = current_env())
vec_slice(x, i) <- value
vec_assign(x, i, value, ..., slice_value = FALSE, x_arg = "", value_arg = "")

Value

A vector of the same type as x.

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

A vector of replacement values

value is cast to the type of x.

If slice_value = FALSE, value must be size 1 or the same size as i after i has been converted to a positive integer location vector with vec_as_location() (which may not be the same size as i originally).

If slice_value = TRUE, value must be size 1 or the same size as x.

slice_value

A boolean. If TRUE, the assignment proceeds as if you had provided vec_slice(x, i) <- vec_slice(value, i), but is optimized to avoid materializing the slice of value.

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()).

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 or assigned to and vec_restore() is called on the result.

• Otherwise, vec_slice() falls back to the base generic [ and vec_slice<-() falls back to the base generic [<-.

When vec_slice<-() falls back to [<-, it is expected that the subclass's [<- method can handle the following subset of cases that base R's [<- can also handle:

• An i vector of positive integer positions (notably excluding NA).

• A value vector of length 1 or length length(i). If length 1, it should be recycled by the [<- method to the length of i.

If your [<- method eventually calls base R's native [<- code, then these cases will be handled for you.

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::`[`

• base::`[<-`

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)

# Slicing `value` -------------------------------------------------

# Sometimes both `x` and `value` start from objects that are the same length,
# and you need to slice `value` by `i` before assigning it to `x`. This comes
# up when thinking about how `base::ifelse()` and `dplyr::case_when()` work.
condition <- c(TRUE, FALSE, TRUE, FALSE)
yes <- 1:4
no <- 5:8

# Create an output container and fill it
out <- vec_init(integer(), 4)
out <- vec_assign(out, condition, vec_slice(yes, condition))
out <- vec_assign(out, !condition, vec_slice(no, !condition))
out

# This is wasteful because you have to materialize the slices of `yes` and
# `no` before they can be assigned, and you also have to validate `condition`
# multiple times. Using `slice_value` internally performs
# `vec_slice(yes, condition)` and `vec_slice(no, !condition)` for you,
# but does so in a way that avoids the materialization.
out <- vec_init(integer(), 4)
out <- vec_assign(out, condition, yes, slice_value = TRUE)
out <- vec_assign(out, !condition, no, slice_value = TRUE)
out