R: Check functions

check_functions {sits} | R Documentation

## 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",
      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)

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

### 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`, `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.

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

[Package sits version 0.15.1 Index]