Scalar type checks

Check if inputs are scalars of an expected type and throw an error if not.

Usage

check_scalar_list(
  x,
  ...,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_atomic(
  x,
  ...,
  allow_na = TRUE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_vector(
  x,
  ...,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_integer(
  x,
  ...,
  allow_na = TRUE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_integerish(
  x,
  ...,
  finite = FALSE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_double(
  x,
  ...,
  finite = FALSE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_complex(
  x,
  ...,
  finite = FALSE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_character(
  x,
  ...,
  allow_na = TRUE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_logical(
  x,
  ...,
  allow_na = TRUE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_raw(
  x,
  ...,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_bytes(
  x,
  ...,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

check_scalar_numeric(
  x,
  ...,
  finite = FALSE,
  allow_null = FALSE,
  arg = caller_arg(x),
  call = caller_env()
)

Arguments

x

An object to check.

...

Additional arguments passed to cli_abort() which forwards unmatched arguments to abort().

allow_null

Whether x is allowed to be NULL.

arg

An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.

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.

allow_na

Whether x is allowed to contain NA values.

finite

Whether x is required to contain only finite values (i.e. no NA, Inf, -Inf, or NaN).

Value

NULL invisibly if the check passes, otherwise an error is thrown.

Details

These functions can be used with the bare() modifier to check if an object is a bare R object (i.e. has no class attribute).

Note

To handle empty strings ("") use check_string() instead of check_scalar_character().

These check functions are wrappers of their corresponding rlang functions. The exception is check_scalar_numeric(), which uses is.numeric().

See also

Other checks: array-type-checks, forbidden-value-checks, inheritance-checks, oop-checks, path-checks, property-checks, s3-type-checks, scalar-value-checks, type-checks, walk-check

Examples

x <- 1L
check_scalar_integer(x)
check_scalar_double(x) |> try()
#> Error in eval(expr, envir) : 
#>   `x` must be a scalar <double>, not the number 1.

check_scalar_list(list(list()))
check_scalar_list(list(1, 2)) |> try()
#> Error in eval(expr, envir) : 
#>   `list(1, 2)` must be a scalar <list>, but it is of length 2.

check_scalar_character(NA_character_, allow_na = FALSE) |> try()
#> Error in eval(expr, envir) : 
#>   `NA_character_` must not be NA.
check_scalar_double(Inf, finite = TRUE) |> try()
#> Error in eval(expr, envir) : 
#>   `Inf` must be a finite value, not Inf.

check_scalar_logical(NULL, allow_null = TRUE)

x <- 1.0
check_scalar_integerish(x)