Skip to contents

Validate Names Within Objects

Source: R/dis_names.R
dis_names.Rd

For any object that can have names, this function can be used to enforce requirements either for names that must be present or names that cannot be present.

Usage

dis_names(x, names, present = FALSE, warn = FALSE, null_valid = TRUE,
    param = NULL, call = NULL, fact_check = "global")

Arguments

x

Required object; a parameter argument to test.

names

Require character vector; the names to test x for.

present

Required logical scalar; if FALSE (default), an error or warning will be generated if the names in names in the names argument are not present. If TRUE, an error or warning will be generated if the names in the names argument are present.

For example, if you wish to enforce a rule that a column named outcome is reserved for your function and any object passed to the function therefore cannot contain outcome, you would set present to TRUE.

Alternatively, if you wish to enforce a rule that a column named outcome must be present in any object passed to the function, you would set present to FALSE (default).

warn

Required logical scalar; if FALSE (default), the function will throw an error based on the condition specified with the present argument. If TRUE, the function will return a warning instead.

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.

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.

Details

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

Examples

# create sample data frame
x <- data.frame(
  a = c(1:5)
)

# define function that requires a column named a and does not allow a column
# named b in the input object
square_a <- function(x){

  ## check inputs with disputeR
  dis_not_missing(.f = rlang::is_missing(x))
  dis_df(x, valid_class = "data.frame")
  dis_names(x, names = "a")
  dis_names(x, names = "b", present = TRUE)

  ## square a
  x$b <- x$a^2

  ## return output
  return(x)

}

# test function
square_a(x)
#>   a  b
#> 1 1  1
#> 2 2  4
#> 3 3  9
#> 4 4 16
#> 5 5 25