vec_assert {vctrs} | R Documentation |
Assert an argument has known prototype and/or size
Description
-
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 |
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 |
call |
The execution environment of a currently
running function, e.g. |
Value
vec_is()
returns TRUE
or FALSE
. vec_assert()
either
throws a typed error (see section on error types) or returns x
,
invisibly.
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"
.
Lifecycle
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()
orobj_check_vector()
for vector checksUse
vec_check_size()
for size checksUse
vec_cast()
,inherits()
, or simple type predicates likerlang::is_logical()
for specific type checks
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.