Package 'assertions'

Description

Assert that conditions are met

Usage

assert(..., msg = NULL, call = rlang::caller_env())

Arguments

Value

invisible(TRUE) if all conditions are met, otherwise aborts with the error message specified by msg

Examples

try({
assert(1 == 1) # Passes
assert(2 == 2, 3 == 3) # Passes
assert(2 == 1, 3 == 3) # Throws default error
assert(2 == 1, 3 == 3, msg = "Custom error message") # Throws custom error
})

Description

Assert that all paths supplied exist and are directories. To assert a single directory exists, see assert_directory_exists()

Usage

assert_all_directories_exist(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is exists and is a directory, otherwise aborts with the error message specified by msg

Examples

try({
assert_directory(system.file("package = assertions")) # PASSES
assert_directory("foo") # Throws Error
})

Description

Assert all files in vector exist. To assert a single file exists, see assert_file_exists()

Usage

assert_all_files_exist(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if all files in x exist, otherwise aborts with the error message specified by msg

Examples

real_file <- system.file("DESCRIPTION", package = "assertions")

try({
assert_all_files_exist(c(real_file, real_file))
assert_all_files_exist(c("foo", "bar")) # Throws Error
})

Description

Assert that all filepaths supplied have one of the selected extensions. Does not require file to actually exist.

Usage

assert_all_files_have_extension(
  x,
  extensions,
  compression = FALSE,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x has any of the specified extensions, otherwise aborts with the error message specified by msg

Examples

try({
assert_all_files_have_extension(c("foo.txt", "bar.txt"), extensions = "txt") # Passes
assert_all_files_have_extension(c("foo.txt", "bar.csv"), extensions = "csv") # Throws Error
})

Description

Assert all elements in a numeric vector/matrix are above some minimum value.

Usage

assert_all_greater_than(
  x,
  minimum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is greater than the specified minimum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_all_greater_than(3, 2) # Passes
assert_all_greater_than(c(2,3,4), 1) # Passes
assert_all_greater_than(c(2,3,4), 2) # Passes
assert_all_greater_than(c(2,3,1), 3) # Throws default error
assert_all_greater_than(c(2,3,1), 3, msg = "custom error message") # Throws custom error
})

Description

Assert all elements in a numeric vector/matrix are above some minimum value.

Usage

assert_all_greater_than_or_equal_to(
  x,
  minimum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is greater than or equal to the specified minimum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_greater_than_or_equal_to(3, 2) # Passes
assert_greater_than_or_equal_to(c(3, 4, 5), 2) # Passes
assert_greater_than_or_equal_to(2, 3) # Throws error
})

Description

Assert all elements in a numeric vector/matrix are below some maximum value.

Usage

assert_all_less_than(
  x,
  maximum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is less than the specified maximum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_all_less_than(1, 2) # Passes
assert_all_less_than(c(1,2,3), 4) # Passes
assert_all_less_than(c(1,2,3), 2) # Throws default error
assert_all_less_than(c(1,2,3), 2, msg = "custom error message") # Throws custom error
})

Description

Assert all elements in a numeric vector/matrix are below or equal to some maximum value.

Usage

assert_all_less_than_or_equal_to(
  x,
  maximum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is less than or equal to the specified maximum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_less_than_or_equal_to(1, 2) # Passes
assert_less_than_or_equal_to(c(1, 2, 3), 3) # Passes
assert_less_than_or_equal_to(3, 2) # Throws error
})

Description

Assert an R object is a 'character' type. Works for vector and matrix objects. To assert an object is specifically a character vector see assert_character_vector()

Usage

assert_character(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a character vector, otherwise aborts with the error message specified by msg

Examples

try({
assert_character("a") # Passes
assert_character("a") # Passes
assert_character(c("a", "b", "c")) # Passes
assert_character(matrix(c('A', 'B', 'C', 'D')))  # Passes
assert_character(1:3) # Throws default error
assert_character(c("a", 1, "b"), "Custom error message") # Throws custom error
})

Description

Assert an object is a character vector. Length 1 character vectors (strings) are considered vectors.

Usage

assert_character_vector(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is a character vector, otherwise aborts with the error message specified by msg

Examples

try({
assert_character_vector(c("a", "b", "c")) # Passes
assert_character_vector(c("a", 1, "b")) # Throws default error
assert_character_vector(matrix(c('A', 'B', 'C', 'D')))  # Throws error since type = matrix
assert_character_vector(c("a", 1, "b"), "Custom error message") # Throws custom error
assert_character_vector(glue::glue('A')) # Throws error
})

Description

Assert an object is a character vector (or a glue vector). Length 1 character vectors (strings) are considered vectors.

Usage

assert_character_vector_or_glue(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is a character vector, otherwise aborts with the error message specified by msg

Examples

try({
assert_character_vector_or_glue(c("a", "b", "c")) # Passes
assert_character_vector_or_glue(glue::glue('A')) # Passes
assert_character_vector_or_glue(c("a", 1, "b")) # Throws default error
assert_character_vector_or_glue(matrix(c('A', 'B', 'C', 'D')))  # Throws error since type = matrix
assert_character_vector_or_glue(c("a", 1, "b"), "Custom error message") # Throws custom error
})

Description

This function asserts that the input object belongs to class

Usage

assert_class(x, class, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x belongs to class, otherwise aborts with the error message specified by msg

Examples

try({
assert_has_class(1, "numeric")  # Passes
assert_has_class(1, "character")  # Throws default error
})

Description

Assert the input object is a database connection, specifically of the "DBIConnection" class, which is the standard virtual class used by the DBI package for database connections. Note this assertion does not test if the database connection is valid and/or active.

Usage

assert_connection(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Details

This function is designed for use with objects inheriting from the "DBIConnection" class, which is used widely across database connection implementations in R. As other database interface packages are introduced, additional checks may be added to support other connection classes.

Value

invisible(TRUE) if x is a valid database connection, otherwise aborts with an error message.

Examples

try({
  # Assuming a valid DBI connection `conn`:
  assert_connection(conn) # Passes if `conn` is a DBI connection

  assert_connection(42) # Fails with error message
})

Description

This function creates an assertion function that can be used to check the validity of an input. All assertions provided with this package are created using either assert_create() or assert_create_chain()

Usage

assert_create(func, default_error_msg = NULL)

Arguments

Value

An assertion function.

Examples

#' # Create an assertion function that checks that a character string is all
# lower case
assert_character <- assert_create(
  is.character,
  "{arg_name} must be a character vector, not a {class(arg_value)}"
)

# Use the assertion function
try({
is_lower("hello") # Returns invisible TRUE
is_lower("Hello") # Aborts the function with the error message
})

Description

Combine multiple assertion functions created by assert_create() into a single assertion function with diverse failure modes and error messages.

Usage

assert_create_chain(...)

Arguments

Value

A single assertion function that calls each of the input functions in the order they are supplied.

Examples

# Create an assertion function that checks for both positive integers and even values
assert_string <- assert_create_chain(
  assert_create(is.character, '{{arg_name}} must be a character'),
  assert_create(function(x){{ length(x)==1 }}, '{{arg_name}} must be length 1')
  )

# Use the assertion function to check a valid value
assert_string("String")

# Use the assertion function to check an invalid value
try({
assert_string(3)
# Output: Error: '3' must be a character
})

Description

Assert input is a data frame

Usage

assert_dataframe(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a data frame, otherwise aborts with the error message specified by msg

Examples

try({
assert_dataframe(mtcars) # Passes
assert_dataframe(data.frame()) # Passes

assert_dataframe(1:10) # Throws default error
assert_dataframe(matrix(1:6, 2, 3)) # Throws default error
assert_dataframe(c(1, 2, 3)) # Throws default error: "Error
assert_dataframe(list(a = 1, b = 2)) # Throws default error
assert_dataframe(factor(c(1, 2, 3))) # Throws default error

assert_dataframe(1:10, msg = "Custom error message") # Throws custom error
})

Description

Assert that a directory does not already exist. Useful for avoiding overwriting. This function is an exact copy of assert_file_does_not_exist() and included to make assertion code more readable.

Usage

assert_directory_does_not_exist(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if directory x does not already exist, otherwise aborts with the error message specified by msg

Examples

real_dir <- system.file("tests", package = "assertions")

try({
assert_directory_does_not_exist("foo") # Passes
assert_directory_does_not_exist(real_dir) # Throws error
assert_directory_does_not_exist(c("foo", "bar")) # Throws Error (single file only)
})

Description

Assert a directory exists. To assert all directories in a vector exist, see assert_all_directories_exist()

Usage

assert_directory_exists(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is exists and is a directory, otherwise aborts with the error message specified by msg

Examples

try({
assert_directory_exists(system.file("package = assertions")) # PASS
assert_all_directories_exist("foo") # Throws Error
})

Description

Is x equal to y. powered by the all.equal() function.

Usage

assert_equal(
  x,
  y,
  tolerance = sqrt(.Machine$double.eps),
  check_names = TRUE,
  check_environment = TRUE,
  check_tzone = TRUE,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is equal to the specified value, otherwise aborts with the error message specified by msg

Examples

try({
assert_equal(3, 3) # Passes
assert_equal(c(3, 3, 3), 3, ) # Fails
assert_equal(2, 3) # Throws error
})

Description

Assert x does not include illegal elements

Usage

assert_excludes(
  x,
  illegal,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x includes any illegal elements, otherwise aborts with the error message specified by msg

Examples

try({
assert_directory(system.file("package = assertions"))
assert_directory("foo") # Throws Error
})

Description

Assert an R object is a factor. Note that no assert_factor function exists since in R factors are always vector quantities (never scalar / in matrices)

Usage

assert_factor_vector(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Details

Technically this function name is misleading, since is.vector(factor(1)) == FALSE but since they act exactly like vectors to end users, I think this name is the most suitable

Value

invisible(TRUE) if x is a factor, otherwise aborts with the error message specified by msg

Examples

try({
assert_factor_vector(factor(c("a", "b", "c"))) # Passes
assert_factor_vector(c("a", "b", "c")) # Throws default error
assert_factor_vector(factor(c("a", "b", "c")), "Custom error message") # Passes
assert_factor_vector(1:3, "Custom error message") # Throws custom error
})

Description

Assert that a file does not exist. Useful for avoiding overwriting.

Usage

assert_file_does_not_exist(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if file x does not exist, otherwise aborts with the error message specified by msg

Examples

real_file <- system.file("DESCRIPTION", package = "assertions")

try({
assert_file_does_not_exist("foo") # Passes
assert_file_does_not_exist(real_file) # Throws error
assert_file_does_not_exist(c("foo", "bar")) # Throws Error (single file only)
})

Description

Assert that a file exists. To assert all files in a vector exist, see assert_all_files_exist()

Usage

assert_file_exists(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if file x exists, otherwise aborts with the error message specified by msg

Examples

real_file <- system.file("DESCRIPTION", package = "assertions")

try({
assert_file_exists(real_file) # PASSES
assert_file_exists("foo") # Throws Error
assert_file_exists(c(real_file, real_file)) # Throws Error (should use assert_all_files_exist)

})

Description

Assert that a filepath includes one of the selected extensions. Does not require file to actually exist.

Usage

assert_file_has_extension(
  x,
  extensions,
  compression = FALSE,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x has any of the specified extensions, otherwise aborts with the error message specified by msg

Examples

try({
assert_file_has_extension("foo.txt", extensions = "txt") # Passes
assert_file_has_extension("file.txt", extensions = "csv") # Throws Error
})

Description

Assert input is a flag (a logical of length 1: TRUE or FALSE)

Usage

assert_flag(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a scalar logical, otherwise aborts with the error message specified by msg

Examples

try({
assert_flag(TRUE) # Passes
assert_flag(FALSE) # Passes
assert_flag(c(TRUE, FALSE)) # Throws default error
assert_flag(1, "Custom error message") # Throws custom error
})

Description

Assert input is a function

Usage

assert_function(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a function, otherwise aborts with the error message specified by msg

Examples

try({
# Assert that a variable is a function
x <- function(a, b) { a + b }
assert_function(x)  # does nothing

# Assert that a variable is not a function
x <- "not a function"
assert_function(x)  # stops execution and prints an error message
})

Description

Assert a function expects n arguments, with user control over how variable arguments (...) are counted (default throws error)

Usage

assert_function_expects_n_arguments(
  x,
  n,
  dots = c("throw_error", "count_as_0", "count_as_1", "count_as_inf"),
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if function x expects exactly n arguments, otherwise aborts with the error message specified by msg

Description

Assert a number is greater than a specified minimum value. To check all numbers in a vector / matrix are above a minimum value, see assert_all_greater_than()

Usage

assert_greater_than(
  x,
  minimum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is greater than the specified minimum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_greater_than(3, 2) # Passes
assert_greater_than(3, 2) # Passes
assert_greater_than(c(2,3,4), 1) # Throws error (Must be a number)
assert_greater_than('A', 1) # Throws error (Must be a number)
assert_greater_than(2, 3, msg = "custom error message") # Throws custom error
})

Description

Assert all elements in a numeric vector/matrix are above or equal to some minimum value. For vectorized version see assert_all_greater_than_or_equal_to()

Usage

assert_greater_than_or_equal_to(
  x,
  minimum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is greater than or equal to the specified minimum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_greater_than_or_equal_to(3, 2) # Passes
assert_greater_than_or_equal_to(c(3, 4, 5), 2) # Throws error
assert_greater_than_or_equal_to(2, 3) # Throws error
})

Description

Assert that the input object is identical to a specified value

Usage

assert_identical(x, y, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is identical to the specified value, otherwise aborts with the error message specified by msg

Examples

try({
assert_identical(3, 3) # Passes
assert_identical(c(3, 3, 3), 3) # Throws error
assert_identical(2, 3) # Throws error
})

Description

Assert x includes required elements

Usage

assert_includes(
  x,
  required,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x includes all required elements, otherwise aborts with the error message specified by msg

Examples

try({
assert_directory(system.file("package = assertions"))
assert_directory("foo") # Throws Error
})

Description

Assert input is an integer

Usage

assert_int(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is an integer, otherwise aborts with the error message specified by msg

Note

In R, integers are whole numbers. Both integers and doubles (numbers with decimals) are considered numeric. This function checks that x specifically belong to the integer class.

Examples

try({
assert_int(1) # Passes
assert_int(1:10) # Passes
assert_int(c(1, 2, 3)) # Passes
assert_int("a") # Throws default error
assert_int(1.5, msg = "Custom error message") # Throws custom error
})

Description

Assert object has a specific length

Usage

assert_length(
  x,
  length,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE)

Description

Assert object length is greater than a threshold

Usage

assert_length_greater_than(
  x,
  length,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE)

Description

Assert object length is greater than or equal to a threshold

Usage

assert_length_greater_than_or_equal_to(
  x,
  length,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE)

Description

Assert object length is less than a threshold

Usage

assert_length_less_than(
  x,
  length,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE)

Description

Assert object length is less than or equal to a threshold

Usage

assert_length_less_than_or_equal_to(
  x,
  length,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE)

Description

Assert a number is less than a specified maximum value. To check all numbers in a vector / matrix are below a maximum value, see assert_all_less_than()

Usage

assert_less_than(
  x,
  maximum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is less than the specified maximum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_less_than(1, 2) # Passes
assert_less_than(1, 2) # Passes
assert_less_than(c(1,2,3), 4) # Throws error (Must be a number)
assert_less_than('A', 1) # Throws error (Must be a number)
assert_less_than(3, 2, msg = "custom error message") # Throws custom error
})

Description

Assert a number is less than or equal to a specified maximum value. For vectorized version see assert_all_less_than_or_equal_to()

Usage

assert_less_than_or_equal_to(
  x,
  maximum,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is less than or equal to the specified maximum value, otherwise aborts with the error message specified by msg

Examples

try({
assert_less_than_or_equal_to(1, 2) # Passes
assert_less_than_or_equal_to(c(1, 2, 3), 3) # Throws error
assert_less_than_or_equal_to(3, 2) # Throws error
})

Description

Assert input is a list

Usage

assert_list(
  x,
  include_dataframes = FALSE,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is a list, otherwise aborts with the error message specified by msg

Examples

try({
# Assert that a variable is a list
x <- list(1, 2, 3)
assert_list(x)  # does nothing

# Assert that a variable is not a list
x <- "not a list"
assert_list(x)  # stops execution and prints an error message
})

Description

Assert an R object is 'logical' (TRUE/FALSE). Works for vector and matrix objects. To assert an object is specifically a logical vector see assert_logical_vector()

Usage

assert_logical(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is logical, otherwise aborts with the error message specified by msg

Examples

try({
assert_logical(TRUE) # Passes
assert_logical(c(TRUE, FALSE, TRUE)) # Passes
assert_logical(c("a", "b")) # Throws default error
assert_logical(1:3, "Custom error message") # Throws custom error
})

Description

Assert input is an atomic logical vector

Usage

assert_logical_vector(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is an atomic logical vector, otherwise aborts with the error message specified by msg

Examples

try({
assert_logical_vector(c(TRUE, TRUE, TRUE)) # Passes
assert_logical_vector("a") # Throws default error
assert_logical_vector(c(1, 0, 1), "Custom error message") # Throws custom error
})

Description

Assert input is a matrix

Usage

assert_matrix(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a matrix, otherwise aborts with the error message specified by msg

Examples

try({
assert_matrix(matrix(1:9, 3)) # Passes
assert_matrix(matrix(1:9, 3, 3)) # Passes
assert_matrix(c(1, 2, 3)) # Throws default error
assert_matrix(1:10, "Custom error message") # Throws custom error
})

Description

Assert that the input object includes a specified name

Usage

assert_names_include(
  x,
  names,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if all names are present in x, otherwise aborts with the error message specified by msg

Examples

try({
x <- list(a = 1, b = 2, c = 3)

assert_includes_name(x, "a") # Passes
assert_includes_name(x, c("a", "b")) # Passes
assert_includes_name(x, c("a", "b", "d")) # Throws default error message

assert_includes_name(x, c("a", "b", "d"), "Custom error message") # Throws custom error message
})

Description

Assert the input vector has no duplicated elements

Usage

assert_no_duplicates(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x has no duplicates, otherwise aborts with the error message specified by msg

Examples

try({
assert_no_duplicates(c(1, 2, 3))  # Passes
assert_no_duplicates(c(1, 2, 2))  # Throws default error

assert_no_duplicates(c(1, 2, 3), msg = "Custom error message")  # Passes
assert_no_duplicates(c(1, 2, 2), msg = "Custom error message")  # Throws custom error
})

Description

This function asserts that the input vector has no missing values (NA) and aborts with an error message if it does.

Usage

assert_no_missing(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x has no missing values (NA), otherwise aborts with the error message specified by msg

Examples

try({
assert_no_missing(c(1, 2, 3))  # Passes
assert_no_missing(c(1, NA, 2))  # Throws default error

assert_no_missing(c(1, 2, 3), msg = "Custom error message")  # Passes
assert_no_missing(c(1, NA, 2), msg = "Custom error message")  # Throws custom error
})

Description

Asserts input is a string, and nonempty (i.e. not equal to ”)

Usage

assert_non_empty_string(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is a character vector, otherwise aborts with the error message specified by msg

Examples

try({
assert_non_empty_string("a") # Passes
assert_non_empty_string("") # Fails
})

Description

This function asserts that the input is not NULL and aborts with an error message if it is.

Usage

assert_non_null(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is not NULL, otherwise aborts with the error message specified by msg.

Examples

# Passes for non-NULL
assert_non_null(1)

try({
 # Throws default error for NULL
 assert_non_null(NULL)

 # Throws custom error message
 assert_non_null(NULL, msg = "Custom error message")
})

Description

This function asserts that the input is NULL and aborts with an error message if it is not.

Usage

assert_null(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is NULL, otherwise aborts with the error message specified by msg.

Examples

assert_null(NULL)  # Passes

try({
 assert_null(1)  # Throws default error
 assert_null(1, msg = "Custom error message")  # Throws custom error
})

Description

A number is a length 1 numeric vector. Numbers can be either integers or doubles.

Usage

assert_number(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a number, otherwise aborts with the error message specified by msg

Examples

assert_number(2) # Passes
try({
assert_number(c(2, 3)) # Throws default error
assert_number("a") # Throws default error
assert_number(c("a", 1, "b"), "Custom error message") # Throws custom error
})

Description

Assert an R object is numeric Works for vector and matrix objects. To assert an object is specifically a numeric vector see assert_numeric_vector()

Usage

assert_numeric(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is numeric, otherwise aborts with the error message specified by msg

Examples

try({
assert_numeric(1:3) # Passes
assert_numeric(1.5:5.5) # Passes
assert_numeric(c("a", "b", "c")) # Throws default error
assert_numeric(c("a", 1, "b"), "Custom error message") # Throws custom error
})

Description

Assert input is a numeric vector

Usage

assert_numeric_vector(
  x,
  msg = NULL,
  call = rlang::caller_env(),
  arg_name = NULL
)

Arguments

Value

invisible(TRUE) if x is a numeric vector, otherwise aborts with the error message specified by msg

Description

Assert x is one of the values of y.

Usage

assert_one_of(x, y, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

Returns invisible(TRUE) if x is a scalar and is one of the values in y, otherwise throws an error

Examples

assert_one_of(3, 1:5) # Passes because 3 is in 1:5
assert_one_of("A", c("A", "B", "C")) # Passes because "A" is in the vector

try({
  assert_one_of("D", c("A", "B", "C")) # Throws error because "D" is not in the vector
})

Description

Assert that x is reactive

Usage

assert_reactive(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a reactive, otherwise aborts with the error message specified by msg

Examples

try({
# Assert that a variable is reactive
x <- shiny::reactive(1)
assert_reactive(x)  # does nothing

# Assert that a variable is not a list
x <- 1
assert_reactive(x)  # stops execution and prints an error message
})

Description

Assert that an object is a scalar, meaning it is a length 1 atomic vector (such as numeric(1), character(1) or logical(1)). Note lists, data.frames and matrices are never considered scalar objects, even if they have only one element.

Usage

assert_scalar(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a scalar, otherwise aborts with the error message specified by msg

Examples

# Pass when value is scalar
assert_scalar(5) # Passes
assert_scalar("single string") # Passes
assert_scalar(TRUE) # Passes

# Fail when value is not
try({
assert_scalar(c(1, 2, 3)) # Throws default error
assert_scalar(matrix(1:4, 2, 2)) # Throws default error
})

Description

This function checks that x and y contain exactly the same elements, ignoring order and duplicates.

Usage

assert_set_equal(x, y, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

Returns invisible(TRUE) if x and y contain all the same elements (ignoring order and duplicates), otherwise throws an error.

Examples

# Passes because elements are the same, order doesn't matter
assert_set_equal(c(1, 2, 3), c(3, 2, 1))

# Passes because elements are identical
assert_set_equal(c("A", "B", "C"), c("C", "A", "B"))

try({
  # Throws error because elements are not identical
  assert_set_equal(c(1, 2, 3), c(1, 2))

  # Throws error because elements differ
  assert_set_equal(c("A", "B"), c("A", "B", "C"))
})

Description

Assert input is a character string

Usage

assert_string(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a string, otherwise aborts with the error message specified by msg

Examples

try({
assert_string("a") # Passes
assert_string(c("a", "b", "c")) # Throws default error
assert_string(1:3) # Throws default error
assert_string(c("a", 1, "b"), "Custom error message") # Throws custom error
})

Description

This function checks that x is a subset of y

Usage

assert_subset(x, y, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

Returns invisible(TRUE) if x is a subset of y, otherwise throws an error

Examples

try({
assert_subset(1:3, 1:5) # Passes
assert_subset(c("A", "B", "C"), c("A", "B")) # Throws error since "C" is not present in first vector
})

Description

Assert input is a vector

Usage

assert_vector(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a vector, otherwise aborts with the error message specified by msg

Note

By default, lists are not considered vectors (i.e. include_lists = FALSE) to align with what end-users will expect, in spite of these objects technically being vectors.

Examples

try({
assert_vector(c(1, 2, 3)) # Passes
assert_vector(matrix(1:6, 2, 3)) # Throws default error message
assert_vector(1:3) # Passes

assert_vector(list(1, 2, 3)) # Throws default error message
assert_vector(list(1, 2, 3), include_lists = TRUE) # Passes

assert_vector(c("a", 1, "b"), "Custom error message") # Throws custom error message
assert_vector(factor(c(1, 2, 3)), "Custom error message") # Throws custom error message
})

Description

Check if x is a whole number (no decimal)

Usage

assert_whole_number(x, msg = NULL, call = rlang::caller_env(), arg_name = NULL)

Arguments

Value

invisible(TRUE) if x is a whole number, otherwise aborts with the error message specified by msg

Examples

try({
assert_whole_number(24) # Passes
assert_whole_number(2.5) # Throws error
})

Description

List all assertion names

Usage

assertion_names(exclude_create_and_chain = TRUE)

Arguments

Value

unique set of assertion names (character)

Description

Count the number of unit-tests per assertion. Note assertion_tests only finds tests where expect_ and assert_ are on the same line.

Usage

assertion_tests()

Value

two column data.frame describing assertion name and number of tests (expect_statement)

Description

Check assertions are tested enough

Usage

check_all_assertions_are_tested_enough(min_required_tests = 5)

Arguments

Value

TRUE if all assertions sufficiently tested. Otherwise throws error

Description

Common Parameter Descriptions

Usage

common_roxygen_params(call, arg_name, msg, ...)

Arguments

Description

This function checks that x does not include any of the illegal elements. x must be the same type as illegal. Factors are treated as character vectors.

Usage

excludes_advanced(x, illegal)

Arguments

Value

Returns TRUE if x is the same type as illegal and x does not include any of the illegal elements. Otherwise returns a string representing the appropriate error message to display

Description

The format_as_bullets function is used for preprocessing character vectors by adding names. These names are used to denote bullet points when the character vector is passed to cli::cli_abort(). This allows for the easy creation of bullet point lists in error messages. The bullet argument allows the user to specify the desired bullet point symbol. The default bullet point symbols are: *, >, , x, v, i, and !.

Usage

format_as_bullets(x, bullet = c("*", ">", " ", "x", "v", "i", "!"))

Arguments

Value

A character string with each element of x formatted as a bullet point

Description

Preprocess character vectors for cli package functions

Usage

format_inline(x, inline_tag = c("strong", "emph", "code", "arg"))

Arguments

Value

A character vector with inline tags applied to each element

Description

This function returns a logical value indicating whether the object x has all the names specified in names.

Usage

has_all_names(x, names)

Arguments

Value

A logical value indicating whether x has all the names specified in names

Description

This function checks whether object is a specific class

Usage

has_class(x, class)

Arguments

Value

A logical scalar indicating x belongs to class

Examples

if(interactive()) {
  has_class(1, "numeric") # TRUE
  has_class(1, "character") # FALSE
}

Description

This function returns a logical value indicating whether the input vector contains duplicated elements.

Usage

has_duplicates(x)

Arguments

Value

A logical value indicating whether the input vector contains duplicated elements.

Examples

if(interactive()){
has_duplicates(c(1, 2, 3))  # returns FALSE
has_duplicates(c(1, 2, 2))  # returns TRUE
}

Description

Has Extension

Usage

has_extension(x, extensions, compression = FALSE)

Arguments

Value

TRUE if all x have valid extensions as supplied by extensions (flag)

Description

This function returns a logical value indicating whether the input vector contains missing values (NA).

Usage

has_missing_values(x)

Arguments

Value

A logical value indicating whether the input vector contains missing values.

Examples

if(interactive()){
has_missing_values(c(1, 2, 3))  # returns FALSE
has_missing_values(c(1, NA, 2))  # returns TRUE
}

Description

This function returns a logical value indicating whether the input vector contains no duplicated elements.

Usage

has_no_duplicates(x)

Arguments

Value

A logical value indicating whether the input vector contains no duplicated elements.

Examples

if(interactive()){
has_no_duplicates(c(1, 2, 3))  # returns TRUE
has_no_duplicates(c(1, 2, 2))  # returns FALSE
}

Description

This function returns a logical value indicating whether the input vector contains no missing values (NA).

Usage

has_no_missing_values(x)

Arguments

Value

A logical value indicating whether the input vector contains no missing values.

Examples

if(interactive()){
has_no_missing_values(c(1, 2, 3))  # returns TRUE
has_no_missing_values(c(1, NA, 2))  # returns FALSE
}

Description

Checks if all elements of required are present in x.

Usage

includes(x, required)

Arguments

Value

A logical value indicating whether all elements of required are present in x (TRUE) or not (FALSE).

Description

This function checks that x includes all of the required elements. x must be the same type as required. Factors are treated as character vectors.

Usage

includes_advanced(x, required)

Arguments

Value

Returns TRUE if x is the same type as required and x includes all the required elements. Otherwise returns a string representing the appropriate error message to display

Description

Check if an object is a character vector

Usage

is_character_vector(x)

Arguments

Value

A logical value indicating whether x is a character vector.

Description

Differs from is_character_vector() in that it permits glue character vectors to pass.

Usage

is_character_vector_or_glue(x)

Arguments

Value

A logical value indicating whether x is a character vector or glue vector.

Description

Is x equal to y. powered by the all.equal() function.

Usage

is_equal(
  x,
  y,
  tolerance = sqrt(.Machine$double.eps),
  check_names = TRUE,
  check_environment = TRUE,
  check_tzone = TRUE
)

Arguments

Value

TRUE if x is equal to y

Examples

if(interactive()){
is_equal(1, 1) #TRUE
is_equal(c(1, 2), 1) #FALSE

is_equal(c("A", "B"), c("A", "B")) #TRUE
is_equal("A", "B") #FALSE
}

Description

This function checks if a value is a logical scalar (i.e., a single logical value).

Usage

is_flag(x)

Arguments

Value

A logical scalar indicating whether x is a logical flag.

Description

This function is designed for use with assert_create_advanced. It must return TRUE for the assertion to pass or a string representing the error message if the assertion should fail.

Usage

is_flag_advanced(x)

Arguments

Value

Returns invisible(TRUE) if x is a logical value with length 1. Returns a string with an error message if x is not a logical value or has a length other than 1.

Description

This function checks if a numeric vector is greater than a specified minimum value. It can also optionally check if all elements of the vector must be greater than the minimum value or if only one element is sufficient

Usage

is_greater_than(x, minimum)

Arguments

Value

A logical value indicating whether all elements of the numeric vector x are greater than the specified minimum value

Examples

if(interactive()){
is_greater_than(c(2,3,4), 1) # TRUE
is_greater_than(c(2,3,4), 2) # TRUE
is_greater_than(c(2,3,1), 3) # FALSE
}

Description

This function checks if a numeric vector is greater than or equal to a specified minimum value. It can also optionally check if all elements of the vector must be greater than or equal to the minimum value or if only one element is sufficient

Usage

is_greater_than_or_equal_to(x, minimum)

Arguments

Value

A logical value indicating whether all elements of the numeric vector x are greater than or equal to the specified minimum value

Examples

if(interactive()){
is_greater_than_or_equal_to(c(2,3,4), 1) # TRUE
is_greater_than_or_equal_to(c(2,3,4), 2) # TRUE
is_greater_than_or_equal_to(c(2,3,1), 3) # FALSE
}

Description

Check if two objects are identical

Usage

is_identical(x, y)

Arguments

Value

logical value indicating whether or not the objects are identical

Description

This function checks if a numeric vector is less than a specified maximum value. It can also optionally check if all elements of the vector must be less than the maximum value or if only one element is sufficient

Usage

is_less_than(x, maximum)

Arguments

Value

A logical value indicating whether all elements of the numeric vector x are less than the specified maximum value

Examples

if(interactive()){
is_less_than(c(1,2,3), 4) # TRUE
is_less_than(c(1,2,3), 2) # FALSE
is_less_than(c(1,2,4), 3) # FALSE
}

Description

This function checks if a numeric vector is less than or equal to a specified maximum value. It can also optionally check if all elements of the vector must be less than or equal to the maximum value or if only one element is sufficient

Usage

is_less_than_or_equal_to(x, maximum)

Arguments

Value

A logical value indicating whether all elements of the numeric vector x are less than or equal to the specified maximum value

Examples

if(interactive()){
is_less_than_or_equal_to(c(1,2,3), 4) # TRUE
is_less_than_or_equal_to(c(1,2,3), 3) # TRUE
is_less_than_or_equal_to(c(1,2,4), 3) # FALSE
}

Description

This function checks if a value is a list. By default, definition of a 'list' excludes data.frames in spite of them technically being lists. This behaviour can be changed by setting include_dataframes = TRUE

Usage

is_list(x, include_dataframes = FALSE)

Arguments

Value

A logical scalar indicating whether x is a list.

Examples

if(interactive()){
is_list(list(1, 2)) # TRUE
is_list(c(1, 2, 3)) # FALSE
is_list(data.frame()) # FALSE
is_list(data.frame(), include_dataframes = TRUE) # TRUE
}

Description

Check if an object is a logical vector

Usage

is_logical_vector(x)

Arguments

Value

A logical value indicating whether x is a logical vector.

Description

This function is designed for use with assert_create. It returns TRUE for the assertion to pass or a string representing the error message if the assertion should fail.

Usage

is_non_empty_string_advanced(x)

Arguments

Value

Returns invisible(TRUE) if x is a character value with length 1 and at least 1 character in string. Returns a string with an error message if x is not a character value or has a length other than 1.

Description

Check if an object is a single number

Usage

is_number(x)

Arguments

Value

A logical value indicating whether x is a single number.

Description

This function is designed for use with assert_create_advanced. It must return TRUE for the assertion to pass or a string representing the error message if the assertion should fail.

Usage

is_number_advanced(x)

Arguments

Value

Returns invisible(TRUE) if x is a numeric value with length 1. Returns a string with an error message if x is not a numeric value or has a length other than 1.

Description

This function checks if an object is a numeric vector in R.

Usage

is_numeric_vector(x)

Arguments

Value

A logical value indicating whether x is a numeric vector.

Examples

if(interactive()){
is_numeric_vector(c(1, 2, 3)) # TRUE
is_numeric_vector(list(1, 2, 3)) # FALSE
is_numeric_vector(1:5) # TRUE
is_numeric_vector("hello") # FALSE
is_numeric_vector(list(1, 2, "a")) # FALSE
}

Description

This function checks if a value is reactive

Usage

is_reactive(x)

Arguments

Value

A logical scalar indicating whether x is a list.

Examples

if(interactive()){
is_reactive(shiny::reactive(1)) # TRUE
is_reactive(1) # FALSE
}

Description

Is type of x the same as y (according to typof)

Usage

is_same_type(x, y)

Arguments

Value

TRUE if x and y are of the same type, otherwise FALSE

Description

Check if an object is a single string

Usage

is_string(x)

Arguments

Value

A logical value indicating whether x is a single string.

Description

This function is designed for use with assert_create. It returns TRUE for the assertion to pass or a string representing the error message if the assertion should fail.

Usage

is_string_advanced(x)

Arguments

Value

Returns invisible(TRUE) if x is a character value with length 1. Returns a string with an error message if x is not a character value or has a length other than 1.

Description

Determines if all elements in set x are also present in set y.

Usage

is_subset(x, y)

Arguments

Value

A logical value indicating whether x is a subset of y.

Description

Determines if all elements in set y are also present in set x.

Usage

is_superset(x, y)

Arguments

Value

A logical value indicating whether x is a superset of y.

Description

Check if an object is a vector This function checks if an object is a vector

Usage

is_vector(x)

Arguments

Value

A logical indicating whether x is a vector

Description

Determine if the two sets are equal.

Usage

setopts_are_equal(x, y)

Arguments

Value

A logical value indicating whether the sets are equal (TRUE) or not (FALSE).

Description

Find the elements that are present in both sets.

Usage

setopts_common_elements(x, y)

Arguments

Value

A vector of elements that are present in both sets.

Description

Counts the number of elements that are in the first set but not in the second set.

Usage

setopts_count_exlusive_to_first(x, y)

Arguments

Value

A scalar representing the number of elements that are in the first set but not in the second set.

Description

Finds the elements that are in the first set but not in the second set.

Usage

setopts_exlusive_to_first(x, y)

Arguments

Value

A vector of elements that are in the first set but not in the second set.

Description

This function returns the number of duplicated values in the input vector.

Usage

util_count_duplicates(x)

Arguments

Value

The number of duplicated values in the input vector.

Examples

if(interactive()) {
util_count_duplicates(c(1, 2, 2))  # returns 1
util_count_duplicates(c(1, 2, 3))  # returns 0
}

Description

This function returns the number of missing values (NA) in the input vector.

Usage

util_count_missing(x)

Arguments

Value

The number of missing values in the input vector.

Examples

if(interactive()){
util_count_missing(c(1, 2, 3))  # returns 0
util_count_missing(c(1, NA, 2))  # returns 1
}

Description

This function returns a vector of the duplicated values in the input vector.

Usage

util_get_duplicated_values(x)

Arguments

Value

A vector of the duplicated values in the input vector.

Examples

if(interactive()) {
util_get_duplicated_values(c(1, 2, 2))  # returns 2
util_get_duplicated_values(c(1, 2, 3))  # returns NULL
}