Check Common Argument Types

Checks whether an argument is an atomic vector (arg_atomic()), a dimensionless atomic vector (arg_vector()), a list (arg_list()), a data frame (arg_data.frame()), a matrix (arg_matrix()), an array (arg_array()), a rectangular data set (arg_data()), or an environment (arg_env()).

Usage

arg_atomic(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_vector(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_list(x, df_ok = FALSE, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_data.frame(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_matrix(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_array(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_data(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

arg_env(x, .arg = rlang::caller_arg(x), .msg = NULL, .call)

Arguments

x

the argument to be checked

.arg

the name of the argument supplied to x to appear in error messages. The default is to extract the argument's name using rlang::caller_arg(). Ignored if .msg is supplied.

.msg

an optional alternative message to display if an error is thrown instead of the default message.

.call

the execution environment of a currently running function, e.g. .call = rlang::current_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to err(). Set to NULL to omit call information. The default is to search along the call stack for the first user-facing function in another package, if any.

df_ok

logical; whether to allow data frames (which are technically lists). Default is FALSE to throw an error on a data frame input.

Value

Returns NULL invisibly if an error is not thrown.

Details

Atomic vectors are checked using is.atomic(). Because matrices are considered atomic vectors, arg_vector() additionally checks that there is no "dims" attribute, i.e., that length(dim(x)) == 0L. arg_data() checks whether x is either a data frame or a matrix. arg_list() checks whether x is a list; when df = FALSE, it throws an error when x is a data frame, even though data frames are lists.

See also

is.atomic(), is.list(), is.data.frame(), is.matrix(), is.array(), is.environment(), arg_is()

Examples

vec <- 1:6
mat <- as.matrix(vec)
dat <- as.data.frame(mat)
lis <- as.list(vec)
nul <- NULL

# arg_atomic
try(arg_atomic(vec))
try(arg_atomic(mat))
try(arg_atomic(dat))
#> Error : `dat` must be an atomic vector.
try(arg_atomic(lis))
#> Error : `lis` must be an atomic vector.
try(arg_atomic(nul))
#> Error : `nul` must be an atomic vector.

# arg_vector
try(arg_vector(vec))
try(arg_vector(mat))
#> Error : `mat` must be a vector.

# arg_matrix
try(arg_matrix(vec))
#> Error : `vec` must be a matrix.
try(arg_matrix(mat))
try(arg_matrix(dat))
#> Error : `dat` must be a matrix.

# arg_data.frame
try(arg_data.frame(vec))
#> Error : `vec` must be a data frame.
try(arg_data.frame(mat))
#> Error : `mat` must be a data frame.
try(arg_data.frame(dat))

# arg_data
try(arg_data(vec))
#> Error : `vec` must be a data frame or matrix.
try(arg_data(mat))
try(arg_data(dat))