vector-checks {vctrs} | R Documentation |
Vector checks
Description
-
obj_is_vector()
tests ifx
is considered a vector in the vctrs sense. See Vectors and scalars below for the exact details. -
obj_check_vector()
usesobj_is_vector()
and throws a standardized and informative error if it returnsFALSE
. -
vec_check_size()
tests ifx
has sizesize
, 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 |
... |
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. |
size |
The size to check for. |
Value
-
obj_is_vector()
returns a singleTRUE
orFALSE
. -
obj_check_vector()
returnsNULL
invisibly, or errors. -
vec_check_size()
returnsNULL
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 byobj_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 avec_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))