Learn R Programming
sits (version 0.13.1)

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, ..., msg = NULL)
.check_names(x, ..., is_named = TRUE, msg = NULL)
.check_length(x, ..., len_min = NULL, len_max = NULL, 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 = NULL,
  len_max = NULL,
  allow_null = FALSE,
  is_named = FALSE,
  msg = NULL
)
.check_num(
  x,
  ...,
  allow_na = FALSE,
  min = -Inf,
  max = Inf,
  allow_zero = TRUE,
  len_min = NULL,
  len_max = NULL,
  allow_null = FALSE,
  is_integer = FALSE,
  is_named = FALSE,
  msg = NULL
)
.check_chr(
  x,
  ...,
  allow_na = FALSE,
  allow_empty = TRUE,
  len_min = NULL,
  len_max = NULL,
  allow_null = FALSE,
  is_named = FALSE,
  regex = NULL,
  msg = NULL
)
.check_lst(
  x,
  ...,
  min_len = NULL,
  max_len = NULL,
  allow_null = FALSE,
  is_named = TRUE,
  fn_check = NULL,
  msg = NULL
)
.check_chr_within(
  x,
  within,
  ...,
  case_sensitive = TRUE,
  discriminator = "all_of",
  msg = NULL
)
.check_chr_contains(
  x,
  contains,
  ...,
  case_sensitive = TRUE,
  discriminator = "all_of",
  msg = NULL
)
.check_file(x, ..., msg = NULL)
.check_env_var(x, ..., msg = NULL)
.check_warn(expr)
.check_error(expr, ..., msg = NULL)

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.

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_na

A logical indicating if the check permits empty NA values. Default is FALSE.

allow_null

A logical indicating if the check permits empty NULL values. Default is FALSE.

min

A atomic vector of numeric indicating the minimum value that the user can provide in function parameter. Only works for numeric check. By default is -Inf.

max

A atomic vector of numeric indicating the maximum value that the user can provide in function parameter. Only works for numeric check. By default is Inf.

allow_zero

A logical indicating if the check permits zero values. Default is TRUE.

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).

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.

expr

A R expression to be evaluated.

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.

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 or max parameters are defined). It also checks for non-zero and integer values (if allow_zero=FALSE and is_integer=TRUE, respectively).

  • .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, or none_of.

  • .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 repeat) of x appears in within vector. any_of: at least one value (can repeat) of x appears in within vector. all_of (default): all values (can repeat) of x appears in within vector. none_of: no value of x is in 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 repeat) of contains appears in x vector. any_of: at least one value (can repeat) of contains appears in x vector. all_of (default): all values (can repeat) of contains appears in x vector. none_of: no value of contains is in x vector.

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.