Scalar value checks

Check if inputs are expected scalar values and throw an error if not.

Usage

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

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

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

check_string(
  x,
  ...,
  string = NULL,
  allow_empty = TRUE,
  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.

string

A character vector of allowed values for x. If NULL, the value is not checked. The check passes if x is any of the values in string.

allow_empty

Whether x is allowed to be an empty string (i.e. when FALSE, "" is not allowed).

Value

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

See also

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

Examples

x <- TRUE
check_true(x)
check_false(x) |> try()
#> Error in eval(expr, envir) : 
#>   `x` must be a single FALSE, not TRUE.

check_bool(NA) |> try()
#> Error in eval(expr, envir) : 
#>   `NA` must be a single TRUE or FALSE, not NA.
check_bool(NULL, allow_null = TRUE)

x <- "a"
check_string(x)
check_string(x, string = c("a", "b"))
check_string(x, string = c("b", "c")) |> try()
#> Error in eval(expr, envir) : 
#>   `x` must be one of "b" or "c".
check_string("", allow_empty = FALSE) |> try()
#> Error in eval(expr, envir) : `""` must not be an empty string.