assert: Assertions

In transltr: Support Many Languages in R

Assertions

Description

These functions are a functional implementation of defensive programming.

⁠is_*()⁠ functions check whether their argument meets certain criteria.

⁠assert_*()⁠ functions further throw an error message when at least one criterion is not met.

Arguments listed below are not explicitly validated for efficiency.

Usage

is_int(x, allow_empty = FALSE)

is_chr(x, allow_empty = FALSE)

is_lgl1(x)

is_int1(x)

is_chr1(x, allow_empty_string = FALSE)

is_list(x, allow_empty = FALSE)

is_between(x, min = -Inf, max = Inf)

is_named(x, allow_empty_names = FALSE, allow_na_names = FALSE)

is_match(x, choices = vector(), allow_partial = FALSE)

assert_int(
  x,
  allow_empty = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_chr(
  x,
  allow_empty = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_lgl1(x, throw_error = TRUE, x_name = deparse(substitute(x)))

assert_int1(x, throw_error = TRUE, x_name = deparse(substitute(x)))

assert_chr1(
  x,
  allow_empty_string = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_list(
  x,
  allow_empty = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_between(
  x,
  min = -Inf,
  max = Inf,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_named(
  x,
  allow_empty_names = FALSE,
  allow_na_names = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_match(
  x,
  choices,
  allow_partial = FALSE,
  quote_values = FALSE,
  throw_error = TRUE,
  x_name = deparse(substitute(x))
)

assert_arg(x, quote_values = FALSE, throw_error = TRUE)

assert(x, ...)

## Default S3 method:
assert(x, ...)

Arguments

x	Any R object.
allow_empty	A non-NA logical value. Should vectors of length 0 be considered as valid values?
allow_empty_string	A non-NA logical value. Should empty character strings be considered as valid values?
min	A non-NA numeric lower bound. It can be infinite.
max	A non-NA numeric upper bound. It can be infinite.
allow_empty_names	A non-NA logical value. Should empty character strings be considered as valid names? This is different from having no names at all.
allow_na_names	A non-NA logical value. Should NA values be considered as valid names?
choices	A non-empty vector of valid candidates.
allow_partial	A non-NA logical value. Should x be partially matched?
throw_error	A non-NA logical value. Should an error be thrown? If so, stops() is called. Otherwise, error messages are returned as a character vector (possibly empty).
x_name	A non-empty and non-NA character string. The name of x.
quote_values	A non-NA logical value. Passed as is to str_to().

Details

Guard clauses tend to be verbose and recycled many times within a project. This makes it hard to keep error messages consistent over time. ⁠assert_*()⁠ functions encapsulate usual guard clause into simple semantic functions. This reduces code repetition and number of required unit tests. See Examples below.

By convention, NA values are always disallowed.

assert_arg() is a partial refactoring of base::match.arg(). It relies on assert_match() internally and does not have an equivalent is_arg() function. It must be called within another function.

assert() is a S3 generic function that covers specific data structures. Classes (and underlying objects) that do not have an assert() method are considered to be valid by default.

Value

is_int(), is_chr(), is_lgl1(), is_int1(), is_chr1(), is_list(), is_between(), is_named(), and is_match() return a logical value.

assert(), assert_int(), assert_chr(), assert_lgl1(), assert_int1(), assert_chr1(), assert_list(), assert_between(), assert_named(), assert_match(), and assert_arg() return an empty character vector if x meets the underlying criteria and throw an error otherwise. If throw_error is FALSE, the error message is returned as a character vector. Unless otherwise stated, the latter is of length 1 (a character string).

assert.default() always returns an empty character vector.

transltr documentation built on April 3, 2025, 9:33 p.m.