Learn R Programming

vctrs (version 0.6.5)

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

Description

[Questioning]

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