check_functions: Check functions

Description

Functions used to check parameters in a systematic way.

Usage

.check_set_caller(caller)
.check_identify_caller()
.check_that(x, ..., local_msg = NULL, msg = NULL)
.check_null(x, ..., msg = NULL)
.check_na(x, ..., allow_na = FALSE, msg = NULL)
.check_require_packages(x, ..., msg = "Please install package(s)")
.check_names(x, ..., is_named = TRUE, msg = NULL)
.check_length(x, ..., len_min = 0, len_max = 2^31 - 1, msg = NULL)
.check_apply(x, fn_check, ...)
.check_lgl_type(x, ..., msg = NULL)
.check_num_type(x, ..., is_integer = FALSE, msg = NULL)
.check_chr_type(x, ..., msg = NULL)
.check_lst_type(x, ..., msg = NULL)
.check_lgl(
  x,
  ...,
  allow_na = FALSE,
  len_min = 0,
  len_max = 2^31 - 1,
  allow_null = FALSE,
  is_named = FALSE,
  msg = NULL
)
.check_num(
  x,
  ...,
  allow_na = FALSE,
  min = -Inf,
  max = Inf,
  exclusive_min = -Inf,
  exclusive_max = Inf,
  len_min = 0,
  len_max = 2^31 - 1,
  allow_null = FALSE,
  is_integer = FALSE,
  is_named = FALSE,
  tolerance = 0,
  msg = NULL
)
.check_chr(
  x,
  ...,
  allow_na = FALSE,
  allow_empty = TRUE,
  len_min = 0,
  len_max = 2^31 - 1,
  allow_null = FALSE,
  is_named = FALSE,
  regex = NULL,
  msg = NULL
)
.check_lst(
  x,
  ...,
  min_len = 0,
  max_len = 2^31 - 1,
  allow_null = FALSE,
  is_named = TRUE,
  fn_check = NULL,
  msg = NULL
)
.check_chr_within(
  x,
  within,
  ...,
  case_sensitive = TRUE,
  discriminator = "all_of",
  can_repeat = TRUE,
  msg = NULL
)
.check_chr_contains(
  x,
  contains,
  ...,
  case_sensitive = TRUE,
  discriminator = "all_of",
  can_repeat = TRUE,
  msg = NULL
)
.check_file(x, ..., extensions = NULL, msg = NULL)
.check_env_var(x, ..., msg = NULL)
.check_warn(expr)
.check_error(expr, ..., msg = NULL)
.check_documentation(progress)

Value

Unless otherwise specified, all checking functions return the same argument as x if a TRUE evaluation occurs.

.check_set_caller() returns NULL.

.check_identify_caller() returns a character value.

The same input value if no error occurs

Arguments

caller: A character value with the caller name.
x: Any object that will be evaluated.
...: Additional parameters for fn_check function.
local_msg: A character with the generic error message that will be shown inside parenthesis.
msg: A character with the error message that will be shown as the main message to the user.
allow_na: A logical indicating if the check permits empty NA values. Default is FALSE.
is_named: A logical indicating if the check permits unnamed list.
len_min: A numeric indicating the minimum length of vector or list users provides for functions. Default is 0.
len_max: A numeric indicating the maximum length of vector or list users provides for functions. Default is 2^31.
fn_check: A function used to test each element of an object.
is_integer: A logical indicating if the value should be integer.
allow_null: A logical indicating if the check permits empty NULL values. Default is FALSE.
min: A atomic vector of numeric indicating the inclusive minimum value that the user can provide in function parameter. Only works for numeric check. By default it is -Inf.
max: A atomic vector of numeric indicating the inclusive maximum value that the user can provide in function parameter. Only works for numeric check. By default it is Inf.
exclusive_min: A atomic vector of numeric indicating the exclusive minimum value that the user can provide in function parameter. Only works for numeric check. By default it is -Inf.
exclusive_max: A atomic vector of numeric indicating the exclusive maximum value that the user can provide in function parameter. Only works for numeric check. By default it is Inf.
tolerance: A numeric with the tolerance to be accepted in range test. The default value is NULL.
allow_empty: A logical indicating if the check permits empty list. Default is TRUE.
regex: A character value with regular expression to be evaluated against data.
min_len: A numeric indicating the minimum length of vector or list users provides for functions. Default is 0.
max_len: A numeric indicating the maximum length of vector or list users provides for functions. Default is 2^31.
within: A character vector indicating a set of elements from which x is a kind of subset. The actual behavior is pointed by discriminator parameter.
case_sensitive: A logical indicating if the check is compared with case sensitive. Default is TRUE.
discriminator: A character value indicating how subset verification will be done (see details).
can_repeat: A logical value indicating if vector x can have repeated elements or not.
contains: A character vector indicating a set of elements to which x is a kind of superset. The actual behavior is pointed by discriminator parameter.
extensions: A character vector with all allowed file extensions.
expr: A R expression to be evaluated.
show_pks_name: A logical value indicating if uninstalled packages can be shown.

Details

Error message functions:

.check_set_caller() should be used to set the caller name that appears in error messages. Any error raised by a check function will show the caller function in its error message. The caller name will be determined by the last call to this function before error occurs. If no call was made, the first function in the calling stack will be used.
.check_identify_caller() searches for the caller name to be shown in error messages. The function searches in calling stack if a call to check_set_caller() was made and returns its value. If no call was found, it returns the first function in calling stack.

General check functions:

.check_that() function checks if the argument in x is logical or not. If it is logical, it will be evaluated as TRUE if all values are TRUE, FALSE otherwise. If the argument is not logical, it will be evaluated as TRUE if its length is greater than zero, FALSE otherwise. If a FALSE evaluation occurs, an error will be raised.
.check_null() throws an error if x argument is NULL.
.check_na() throws an error if any element of x is NA.
.check_names() throws an error if x does not have names and is_named argument is TRUE (and vice-versa). This function checks for empty or duplicated names if is_named is TRUE.
.check_length() throws an error if length of x is out of the range specified by len_min and len_max (both inclusive).
.check_apply() throws an error only if fn_check function throws an error when applied to each x element.

Check type functions:

.check_lgl_type() throws an error if x type is not logical.
.check_num_type() throws an error if x type is not numeric. Also, an error will be throw if x values are not integer and is_integer parameter is TRUE.
.check_int_type() throws an error if x type is not numeric with integer values.
.check_chr_type() throws an error if x type is not character.
.check_lst_type() throws an error if x type is not list.

Combined check functions. These function combine some checks mentioned above in one place. In general, these functions can check for NA (if allow_na=FALSE), for value length (if either len_min and len_max are defined - for list the parameters are min_len and max_len, respectively), for NULL value (if allow_null=FALSE), and for names (if is_named is TRUE or FALSE). Depending on specific type, the functions also check for:

.check_lgl() checks for logical values.
.check_num() checks for numeric values and its range (if either min, max, exclusive_min, or exclusive_max parameters are defined). It also checks integer values (if is_integer=TRUE).
.check_chr() checks for character type and empty strings (if allow_empty=FALSE). It also checks strings through regular expression (if regex parameter is defined).
.check_lst() checks for list type. By default, it checks if the list is named. Additionally, a function can be passed to fn_check parameter to check its elements. This enables to pass other checking functions like .check_num() to verify the type of its elements. In this case, extra parameters can be passed by ....

Subset check functions. Two functions are provided to check for subset elements in character vectors. These functions are the symmetrical equivalent to each other, but the error messages are different. For the .check_chr_within(), the error message focus on the within values. For the .check_chr_contains(), the error message focus on the contains values. The verification is done accordingly to the discriminator parameter, that can be: one_of, any_of, all_of, none_of, or exactly.

.check_chr_within() throws an error if provided within vector does not correspond to the discriminator with respect to x parameter (e.g. "one of x within...", "all of x within...). one_of: only one value (can it repeat?) of x appears in within vector. any_of: at least one value (can it repeat?) of x appears in within vector. all_of (default): all values (can it repeat?) of x appears in within vector. none_of: no value of x is in within vector. exactly: value of x (can it repeat?) is equal to within vector.
.check_chr_contains() throws an error if provided x vector does not correspond to the discriminator with respect to contains parameter (e.g. "x contains one of...", "x contains all of..."). one_of: only one value (can it repeat?) of contains appears in x vector. any_of: at least one value (can it repeat?) of contains appears in x vector. all_of (default): all values (can it repeat?) of contains appears in x vector. none_of: no value of contains is in x vector. exactly: value of contains is exactly (can it repeat?) equal to x.

Special checking function:

.check_file() throws an error if provided value is not a valid and existing file path.

Special checking function:

.check_env_var() throws an error if provided environment variable is not existing.

Contextual check and error conversion functions:

.check_warn() converts an error raised by an R expression in expr parameter into a warning message.
.check_error() captures any error raised by an R expression in expr parameter, and shows a personalized message.