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.

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() 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

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