check_parameter_type {W4MRUtils}

check_parameter_type - validate parameter's type

Description

Use this function to validate parameters. You're never assured that provided parameters from users are the right type, or length. This may be the case with your own code as well, if you have undetected bugs in your code.

This function helps prevent unpredictable behaviour coming from bad parameters.

It checks the size of vectors, and the type of values. If the parameter is not the good type or length, the program stops with an explanatory error.

Usage

check_parameter_type(
  value,
  expected_type,
  nth = NULL,
  func_name = NULL,
  param_name = NULL,
  or_null = FALSE,
  nframe = 1
)

Arguments

value

The parameter to test.

expected_type

The chararcter vector of the kind: "character", "integer", "logical", ...

nth

This parameter is used in the error message generation. Provide a character vector like "first", "second", "1st", "2nd", ... this must be the number of the parameter if the function.

func_name

By default, the function name is guessed from the stack. But if you want to change it, or if it is not the right function name in error messages, set the right one here.

param_name

Like func_name, by default the param name is guessed. But if you want to change it, or if it is not the right parameter name in error messages, set the right one here.

or_null

When we check the parameter's type, if or_null is TRUE and the value is NULL, then, the type check does not occur

nframe

The number of function calls between this function and the function where the value to test is a parameter. for example, if a user calls function A, which calls check_param_* directly, then nframe must be 1 because it is a direct call. But, if the user has called function A, and function A calls function B, and check_param_, is called in function B, then, for check_param_ to understant it is a parameter comming from function A (and not from function B), we have to tell check_param_* that nframe is 2. If the function name is not the right name, it may be because of that. So don't fear testing different values for nframes.

Author(s)

L.Pavot

See Also

check_parameter_type,check_parameter_length

check_one_integer,check_one_logical,check_one_numeric

check_one_complex,check_one_character

Examples

## here is a simple utility function we will use in this example.
## It is not important
show_last_error <- function(error) {
  dump.frames()
  message(base::attr(last.dump, "error.message"))
}

## The example really starts here
## we have a simple function like this:
custom_message <- function(text) {
  message(sprintf("Message: %s", text))
}

## this function needs to have a character vector as first
## parameter.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(42), error = show_last_error)


## this function needs to have a vector of length 1.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  check_parameter_length(text, 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)


## Or, to be more concise:
custom_message <- function(text) {
  check_param_type_n_length(text, "character", 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)
tryCatch(custom_message(42), error = show_last_error)


## Let's say the text can be 1 or more elements, and can be null.
custom_message <- function(text) {
  check_param_type_n_length(
    text,
    expected_type = "character",
    or_null = TRUE,
    expected_size = 1,
    or_more = TRUE
  )
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(custom_message(c(42, 43)), error = show_last_error)
tryCatch(custom_message(NULL), error = show_last_error)
## no error, because or_null is TRUE
tryCatch(custom_message(character(0)), error = show_last_error)
tryCatch(custom_message(c("uwu", ":3")), error = show_last_error)
## no error, because or_more is TRUE

## With a function that has a lot of parameters, it may be usefull to
## provide the parameter's number. And, because it becomes very long
## to test all those parameters, we will use shortcuts functions
write_msg <- function(
  text,
  font = "owo",
  font_size = 16,
  italic = FALSE,
  bold = FALSE
) {
  check_one_character(text, nth = "1st")
  check_one_character(font, nth = "2nd")
  check_one_numeric(font_size, nth = "3rd")
  check_one_logical(italic, nth = "before last")
  check_one_logical(bold, nth = "last")
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(write_msg(text = 42, "font", 16), error = show_last_error)
tryCatch(write_msg("uwu", font = 1, 16), error = show_last_error)
tryCatch(write_msg("uwu", font_size = "16"), error = show_last_error)
tryCatch(write_msg("uwu", italic = "FALSE"), error = show_last_error)
tryCatch(write_msg("uwu", bold = "FALSE"), error = show_last_error)