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.
Usage
vec_assert(
x,
ptype = NULL,
size = NULL,
arg = caller_arg(x),
call = caller_env()
)
vec_is(x, ptype = NULL, size = NULL)
Arguments
- x
A vector argument to check.
- ptype
Prototype to compare against. If the prototype has a class, its
vec_ptype()
is compared to that ofx
withidentical()
. Otherwise, itstypeof()
is compared to that ofx
with==
.- size
A single integer size against which to compare.
- arg
Name of argument being checked. This is used in error messages. The label of the expression passed as
x
is taken as default.- 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 thecall
argument ofabort()
for more information.
Value
vec_is()
returns TRUE
or FALSE
. vec_assert()
either
throws a typed error (see section on error types) or returns x
,
invisibly.
Scalars and vectors
Informally, a vector is a collection that makes sense to use as column in a data frame. An object is a vector if one of the following conditions hold:
A
vec_proxy()
method is implemented for the class of the object.The base type of the object is atomic:
"logical"
,"integer"
,"double"
,"complex"
,"character"
,"raw"
The object is a data.frame.
The base type is
"list"
, and one of:The object is a bare
"list"
without a"class"
attribute.The object explicitly inherits from
"list"
. That is, the"class"
attribute contains"list"
andinherits(x, "list")
isTRUE
.
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.
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
"class"
attribute are not treated as vectors. If you inherit from an S3 class, always prepend your class to the"class"
attribute for correct dispatch.
Error types
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"
.