Skip to contents

Validate Character Arguments

Source: R/dis_character.R
dis_character.Rd

This function runs standard unit tests on character parameters for functions.

Usage

dis_character(x, valid = NULL, null_valid = TRUE, empty_valid = FALSE,
    scalar = TRUE, param = NULL, call = NULL, fact_check = "global")

Arguments

x

Required object; a parameter argument to test.

valid

Optional character scalar or vector; valid values for the parameter.

null_valid

Required logical scalar; whether the parameter can be NULL. If FALSE, the function will throw an error if x is NULL. Default is TRUE.

empty_valid

Required logical scalar; whether the parameter can be an empty string. If FALSE (default), the function will throw an error if x is an empty string. If TRUE, the function will allow an empty string.

scalar

Required logical scalar; whether the parameter must be a scalar. If TRUE (default), the function will throw an error if x is not a scalar.

param

Optional character scalar; the parameter name. If NULL (default), the function will attempt to determine the parameter name from the calling environment. If nesting functions, it is recommended to provide the parameter name to ensure the correct parameter is referenced using rlang::caller_arg().

call

Optional environment; the environment in which the function was called. If NULL (default), the function will attempt to determine the calling environment. If nesting functions, it is recommended to provide the calling environment to ensure the correct environment is referenced using rlang::caller_env().

fact_check

Required character scalar; whether to override fact checking environment setting. If "global" (default), dis_character will follow the global setting. If "always", dis_character will ignore any global setting and will always check x. This argument is primarily intended for Shiny developers who wish to use disputeR in modules. See the vignette on vignette("developing", package = "disputeR") for details on how to use this function.

Value

This function will return either TRUE (if x passes all validation checks) or FALSE (if the validation checks are skipped). If x fails validation checks, an error message will be returned. Note that, if the input is NULL and null_valid is set to TRUE, the detailed unit tests are skipped and the function will return TRUE.

Details

See the vignette on vignette("developing", package = "disputeR") for details about internal validation of arguments for this function.

Examples

# create example function that uses dis_character()
example <- function(x){

  ## check inputs with disputeR
  dis_not_missing(.f = rlang::is_missing(x))
  dis_character(x, null_valid = FALSE)

  ## modify string
  out <- paste0(x, " rules!")

  ## return output
  return(out)

}

# test example function
example(x = "R")
#> [1] "R rules!"