vec_assert: 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)

Value

vec_is() returns TRUE or FALSE. vec_assert() either throws a typed error (see section on error types) or returns x, invisibly.

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 of x with identical(). Otherwise, its typeof() is compared to that of x 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 the call argument of abort() for more information.

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" and inherits(x, "list") is TRUE.

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".