vector-checks: Vector checks

In vctrs: Vector Helpers

Vector checks

Description

• obj_is_vector() tests if x is considered a vector in the vctrs sense. See Vectors and scalars below for the exact details.

• obj_check_vector() uses obj_is_vector() and throws a standardized and informative error if it returns FALSE.

• vec_check_size() tests if x has size size, and throws an informative error if it doesn't.

Usage

obj_is_vector(x)

obj_check_vector(x, ..., arg = caller_arg(x), call = caller_env())

vec_check_size(x, size, ..., arg = caller_arg(x), call = caller_env())

Arguments

x	For ⁠obj_*()⁠ functions, an object. For ⁠vec_*()⁠ functions, a vector.
...	These dots are for future extensions and must be empty.
arg	An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.
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.
size	The size to check for.

Value

• obj_is_vector() returns a single TRUE or FALSE.

• obj_check_vector() returns NULL invisibly, or errors.

• vec_check_size() returns NULL invisibly, or errors.

Vectors and scalars

Informally, a vector is a collection that makes sense to use as column in a data frame. The following rules define whether or not x is considered a vector.

If no vec_proxy() method has been registered, x is a vector if:

• The base type of the object is atomic: "logical", "integer", "double", "complex", "character", or "raw".

• x is a list, as defined by obj_is_list().

• x is a data.frame.

If a vec_proxy() method has been registered, x is a vector if:

• The proxy satisfies one of the above conditions.

• The base type of the proxy is "list", regardless of its class. S3 lists are thus treated as scalars unless they implement a vec_proxy() method.

Otherwise an object is treated as scalar and cannot be used as a vector. In particular:

• NULL is not a vector.

• S3 lists like lm objects are treated as scalars by default.

• Objects of type expression are not treated as vectors.

Technical limitations

• Support for S4 vectors is currently limited to objects that inherit from an atomic type.

• Subclasses of data.frame that append their class to the back of the "class" attribute are not treated as vectors. If you inherit from an S3 class, always prepend your class to the front of the "class" attribute for correct dispatch. This matches our general principle of allowing subclasses but not mixins.

Examples

obj_is_vector(1)

# Data frames are vectors
obj_is_vector(data_frame())

# Bare lists are vectors
obj_is_vector(list())

# S3 lists are vectors if they explicitly inherit from `"list"`
x <- structure(list(), class = c("my_list", "list"))
obj_is_list(x)
obj_is_vector(x)

# But if they don't explicitly inherit from `"list"`, they aren't
# automatically considered to be vectors. Instead, vctrs considers this
# to be a scalar object, like a linear model returned from `lm()`.
y <- structure(list(), class = "my_list")
obj_is_list(y)
obj_is_vector(y)

# `obj_check_vector()` throws an informative error if the input
# isn't a vector
try(obj_check_vector(y))

# `vec_check_size()` throws an informative error if the size of the
# input doesn't match `size`
vec_check_size(1:5, size = 5)
try(vec_check_size(1:5, size = 4))

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