vec_is()
is a predicate that checks if its input is a vector that
conforms to a prototype and/or a size.
vec_assert()
throws an error when the input is not a vector or
doesn't conform.
vec_assert(
x,
ptype = NULL,
size = NULL,
arg = caller_arg(x),
call = caller_env()
)vec_is(x, ptype = NULL, size = NULL)
vec_is()
returns TRUE
or FALSE
. vec_assert()
either
throws a typed error (see section on error types) or returns x
,
invisibly.
A vector argument to check.
Prototype to compare against. If the prototype has a
class, its vec_ptype()
is compared to that of x
with
identical()
. Otherwise, its typeof()
is compared to that of
x
with ==
.
A single integer size against which to compare.
Name of argument being checked. This is used in error
messages. The label of the expression passed as x
is taken as
default.
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.
vec_is()
never throws.
vec_assert()
throws the following errors:
If the input is not a vector, an error of class
"vctrs_error_scalar_type"
is raised.
If the prototype doesn't match, an error of class
"vctrs_error_assert_ptype"
is raised.
If the size doesn't match, an error of class
"vctrs_error_assert_size"
is raised.
Both errors inherit from "vctrs_error_assert"
.
Both vec_is()
and vec_assert()
are questioning because their ptype
arguments have semantics that are challenging to define clearly and are
rarely useful.
Use obj_is_vector()
or obj_check_vector()
for vector checks
Use vec_check_size()
for size checks
Use vec_cast()
, inherits()
, or simple type predicates like
rlang::is_logical()
for specific type checks
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.