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

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 = as_label(substitute(x)))

    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` | Size to compare against
`arg` | Name of argument being checked. This is used in error messages. The label of the expression passed as `x` is taken as default.

### Value

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

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

[Package vctrs version 0.3.2 Index]