vec_assert: Assert an argument has known prototype and/or size

In vctrs: Vector Helpers

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

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

vctrs documentation built on May 29, 2024, 11:39 a.m.