Package 'stbl'

Description

are_chr_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to a character vector. are_character_ish() is a synonym of are_chr_ish().

is_chr_ish() is a scalar predicate function that checks if all elements of its input can be safely coerced to a character vector. is_character_ish() is a synonym of is_chr_ish().

Usage

are_chr_ish(x, ...)

is_chr_ish(x, ...)

are_character_ish(x, ...)

is_character_ish(x, ...)

## Default S3 method:
are_chr_ish(x, ..., depth = 1)

Arguments

Value

are_chr_ish() returns a logical vector with the same length as the input. is_chr_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE) for the entire vector.

See Also

Other character functions: specify_chr(), stabilize_chr(), stabilize_chr_scalar(), to(), to_chr(), to_chr_scalar()

Other check functions: are_dbl_ish(), are_fct_ish(), are_fn_ish(), are_int_ish(), are_lgl_ish()

Examples

are_chr_ish(letters)
is_chr_ish(letters)

are_chr_ish(1:10)
is_chr_ish(1:10)

are_chr_ish(list("a", 1, TRUE))
is_chr_ish(list("a", 1, TRUE))

are_chr_ish(list("a", 1, list(1, 2)))
is_chr_ish(list("a", 1, list(1, 2)))

Description

are_dbl_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to a double vector. are_double_ish() is a synonym of are_dbl_ish().

is_dbl_ish() is a scalar predicate function that checks if all elements of its input can be safely coerced to a double vector. is_double_ish() is a synonym of is_dbl_ish().

Usage

are_dbl_ish(x, ...)

is_dbl_ish(x, ...)

are_double_ish(x, ...)

is_double_ish(x, ...)

## S3 method for class 'character'
are_dbl_ish(x, ..., coerce_character = TRUE)

## S3 method for class 'factor'
are_dbl_ish(x, ..., coerce_factor = TRUE)

## Default S3 method:
are_dbl_ish(x, ..., depth = 1)

Arguments

Value

are_dbl_ish() returns a logical vector with the same length as the input. is_dbl_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE) for the entire vector.

See Also

Other double functions: specify_dbl(), stabilize_dbl(), stabilize_dbl_scalar(), to(), to_dbl(), to_dbl_scalar()

Other check functions: are_chr_ish(), are_fct_ish(), are_fn_ish(), are_int_ish(), are_lgl_ish()

Examples

are_dbl_ish(c(1.0, 2.2, 3.14))
is_dbl_ish(c(1.0, 2.2, 3.14))

are_dbl_ish(1:3)
is_dbl_ish(1:3)

are_dbl_ish(c("1.1", "2.2", NA))
is_dbl_ish(c("1.1", "2.2", NA))

are_dbl_ish(c("a", "1.0"))
is_dbl_ish(c("a", "1.0"))

are_dbl_ish(list(1, "2.2", "c"))
is_dbl_ish(list(1, "2.2", "c"))

are_dbl_ish(c(1 + 1i, 1 + 0i, NA))
is_dbl_ish(c(1 + 1i, 1 + 0i, NA))

Description

are_fct_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to a factor. are_factor_ish() is a synonym of are_fct_ish().

is_fct_ish() is a scalar predicate function that checks if all elements of its input can be safely coerced to a factor. is_factor_ish() is a synonym of is_fct_ish().

Usage

are_fct_ish(x, ..., levels = NULL, to_na = character())

is_fct_ish(x, ..., levels = NULL, to_na = character(), max_levels = Inf)

are_factor_ish(x, ..., levels = NULL, to_na = character())

is_factor_ish(x, ..., levels = NULL, to_na = character(), max_levels = Inf)

## Default S3 method:
are_fct_ish(x, ..., levels = NULL, to_na = character(), depth = 1)

Arguments

Value

are_fct_ish() returns a logical vector with the same length as the input. is_fct_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE) for the entire vector.

See Also

Other factor functions: specify_fct(), stabilize_fct(), stabilize_fct_scalar(), to(), to_fct(), to_fct_scalar()

Other check functions: are_chr_ish(), are_dbl_ish(), are_fn_ish(), are_int_ish(), are_lgl_ish()

Examples

# When `levels` is `NULL`, atomic vectors are fct_ish, but nested lists are
# not.
are_fct_ish(c("a", 1, NA))
is_fct_ish(c("a", 1, NA))
are_fct_ish(list("a", list("b", "c")))
is_fct_ish(list("a", list("b", "c")))

# When `levels` is specified, values must be in `levels` or `to_na`.
are_fct_ish(c("a", "b", "c"), levels = c("a", "b"))
is_fct_ish(c("a", "b", "c"), levels = c("a", "b"))

# The `to_na` argument allows some values to be treated as `NA`.
are_fct_ish(c("a", "b", "z"), levels = c("a", "b"), to_na = "z")
is_fct_ish(c("a", "b", "z"), levels = c("a", "b"), to_na = "z")

# `max_levels` limits distinct non-`NA` values across the whole vector.
is_fct_ish(c("a", "b", "c"), max_levels = 2)

# Factors are also checked against the specified levels.
are_fct_ish(factor(c("a", "b", "c")), levels = c("a", "b"))
is_fct_ish(factor(c("a", "b", "c")), levels = c("a", "b"))

Description

are_fn_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to a function. are_function_ish() is a synonym of are_fn_ish().

is_fn_ish() is a scalar predicate that checks whether its input can be safely coerced to a function by to_fn(). is_function_ish() is a synonym of is_fn_ish().

Usage

are_fn_ish(x, ...)

are_function_ish(x, ...)

is_fn_ish(x, ...)

is_function_ish(x, ...)

Arguments

Details

are_fn_ish() returns TRUE for:

• Functions (including lambda functions created with ~ or ⁠\()⁠)

• Formulas (one-sided or two-sided, coercible via rlang::as_function())

• Character strings that are syntactically valid function names: either a bare name ("mean") or a namespaced name ("pkg::fn"). The check is syntactic; it does not verify that the named function exists in any environment.

is_fn_ish() returns TRUE for objects that to_fn() can coerce without error (assuming a matching function exists in the search path):

• Functions (including lambda functions created with ~ or ⁠\()⁠)

• One-sided or two-sided formulas

• Single non-NA character strings (including namespaced "pkg::fn" names)

NULL and length-0 character vectors are not considered function-ish because they do not represent a callable object; to_fn() converts them to NULL only as a permissive special case controlled by allow_null.

Value

are_fn_ish() returns a logical vector with the same length as the input. is_fn_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE).

See Also

Other function functions: to(), to_fn()

Other check functions: are_chr_ish(), are_dbl_ish(), are_fct_ish(), are_int_ish(), are_lgl_ish()

Examples

are_fn_ish(mean)
are_fn_ish(~ . + 1)
are_fn_ish(c("mean", "stats::median", NA, "", "1bad"))
are_fn_ish(NULL)
are_fn_ish(1L)

is_fn_ish(mean)
is_fn_ish("mean")
is_fn_ish("stats::median")
is_fn_ish(~ . + 1)
is_fn_ish(NULL)
is_fn_ish(1L)

Description

are_int_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to an integer vector. are_integer_ish() is a synonym of are_int_ish().

is_int_ish() is a scalar predicate function that checks if all elements of its input can be safely coerced to an integer vector. is_integer_ish() is a synonym of is_int_ish().

Usage

are_int_ish(x, ...)

is_int_ish(x, ...)

are_integer_ish(x, ...)

is_integer_ish(x, ...)

## S3 method for class 'character'
are_int_ish(x, ..., coerce_character = TRUE)

## S3 method for class 'factor'
are_int_ish(x, ..., coerce_factor = TRUE)

## Default S3 method:
are_int_ish(x, ..., depth = 1)

Arguments

Value

are_int_ish() returns a logical vector with the same length as the input. is_int_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE) for the entire vector.

See Also

Other integer functions: specify_int(), stabilize_int(), stabilize_int_scalar(), to(), to_int(), to_int_scalar()

Other check functions: are_chr_ish(), are_dbl_ish(), are_fct_ish(), are_fn_ish(), are_lgl_ish()

Examples

are_int_ish(1:4)
is_int_ish(1:4)

are_int_ish(c(1.0, 2.0, 3.00000))
is_int_ish(c(1.0, 2.0, 3.00000))

are_int_ish(c("1.0", "2.0", "3.00000"))
is_int_ish(c("1.0", "2.0", "3.00000"))

are_int_ish(c(1, 2.2, NA))
is_int_ish(c(1, 2.2, NA))

are_int_ish(c("1", "1.0", "1.1", "a"))
is_int_ish(c("1", "1.0", "1.1", "a"))

are_int_ish(factor(c("1", "a")))
is_int_ish(factor(c("1", "a")))

Description

are_lgl_ish() is a vectorized predicate function that checks whether each element of its input can be safely coerced to a logical vector. are_logical_ish() is a synonym of are_lgl_ish().

is_lgl_ish() is a scalar predicate function that checks if all elements of its input can be safely coerced to a logical vector. is_logical_ish() is a synonym of is_lgl_ish().

Usage

are_lgl_ish(x, ...)

is_lgl_ish(x, ...)

are_logical_ish(x, ...)

is_logical_ish(x, ...)

## Default S3 method:
are_lgl_ish(x, ..., depth = 1)

Arguments

Value

are_lgl_ish() returns a logical vector with the same length as the input. is_lgl_ish() returns a ⁠length-1 logical⁠ (TRUE or FALSE) for the entire vector.

See Also

Other logical functions: specify_lgl(), stabilize_lgl(), stabilize_lgl_scalar(), to(), to_lgl(), to_lgl_scalar()

Other check functions: are_chr_ish(), are_dbl_ish(), are_fct_ish(), are_fn_ish(), are_int_ish()

Examples

are_lgl_ish(c(TRUE, FALSE, NA))
is_lgl_ish(c(TRUE, FALSE, NA))

are_lgl_ish(c(1, 0, 1.0, NA))
is_lgl_ish(c(1, 0, 1.0, NA))

are_lgl_ish(c("T", "F", "TRUE", "FALSE", "true", "false", "1", "0"))
is_lgl_ish(c("T", "F", "TRUE", "FALSE", "true", "false", "1", "0"))

are_lgl_ish(c("T", "F", "a", "1.1"))
is_lgl_ish(c("T", "F", "a", "1.1"))

are_lgl_ish(factor(c("T", "a")))
is_lgl_ish(factor(c("T", "a")))

are_lgl_ish(list(TRUE, 0, "F", "a"))
is_lgl_ish(list(TRUE, 0, "F", "a"))

Description

assert_contains() applies spec to each element of x independently and counts how many elements match. It returns x unchanged if that count falls between min_matches and max_matches (inclusive), and errors otherwise.

Usage

assert_contains(
  x,
  spec,
  ...,
  min_matches = 1,
  max_matches = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x, unchanged, if the number of elements of x matching spec is between min_matches and max_matches, or an error condition with classes ⁠<stbl-error>⁠, ⁠<stbl-condition>⁠, ⁠<rlang_error>⁠, ⁠<error>⁠, ⁠<condition>⁠, and a specific class by failure mode:

• ⁠<stbl-error-too_few_matches>⁠ when fewer than min_matches elements match spec.

• ⁠<stbl-error-too_many_matches>⁠ when more than max_matches elements match spec.

See Also

Other stabilization functions: assert_not(), assert_present(), stabilize_all_of(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

# By default, at least 1 element must match spec
assert_contains(list("1", "a", "b"), stabilize_int)

# Require at least 2 matching elements
assert_contains(list("1", "2", "a"), stabilize_int, min_matches = 2)

# Errors because no elements are int-ish
try(assert_contains(list("a", "b"), stabilize_int))

# Errors because too many elements are int-ish
try(assert_contains(list("1", "2", "3"), stabilize_int, max_matches = 2))

# spec is applied to each element, not to x as a whole, so a scalar spec
# like stabilize_int_scalar() still matches every element of a list
assert_contains(
  list(1L, 2L, 3L),
  stabilize_int_scalar,
  min_matches = 2,
  max_matches = 3
)

# Use min_matches = 0 to check only an upper bound on the number of matches
 assert_contains(
   list("1", "a", "b"),
   stabilize_int,
   min_matches = 0,
   max_matches = 1
 )

Description

assert_not() is the inverse of a single specification: it errors when x would be accepted by spec, and returns x unchanged otherwise.

Usage

assert_not(
  x,
  spec,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x, unchanged, if x does not match spec, or an error condition with classes ⁠<stbl-error>⁠, ⁠<stbl-condition>⁠, ⁠<rlang_error>⁠, ⁠<error>⁠, ⁠<condition>⁠, and ⁠<stbl-error-matched_spec>⁠ when x matches spec.

See Also

Other stabilization functions: assert_contains(), assert_present(), stabilize_all_of(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

assert_not("a", specify_int())
assert_not(1.5, stabilize_int)

# Errors because "1" is int-ish, even though it isn't literally an integer
try(assert_not("1", specify_int()))

# Errors because stabilize_int() succeeds outright on 1L
try(assert_not(1L, stabilize_int))

Description

assert_present() validates that a value is not NULL. Any non-NULL value passes through unchanged. This is useful as an element specification in stabilize_lst() when you need to require a named element without imposing any type constraints on its value.

Usage

assert_present(
  x,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The value, unchanged.

See Also

Other list functions: specify_lst(), stabilize_lst(), to(), to_lst()

Other stabilization functions: assert_contains(), assert_not(), stabilize_all_of(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

assert_present("any value")
assert_present(list(1, 2, 3))
try(assert_present(NULL))

# Use as a named element spec in stabilize_lst()
stabilize_lst(list(data = mtcars), data = assert_present)

Description

When you use pkg_abort() to signal errors, you can use this function to test that those errors are generated as expected.

Usage

expect_pkg_error_classes(object, package, ...)

Arguments

Value

The classes of the error invisibly on success or the error on failure. Unlike most testthat expectations, this expectation cannot be usefully chained.

Examples

expect_pkg_error_classes(
  pkg_abort("stbl", "This is a test error", "test_subclass"),
  "stbl",
  "test_subclass"
)
try(
  expect_pkg_error_classes(
    pkg_abort("stbl", "This is a test error", "test_subclass"),
    "stbl",
    "different_subclass"
  )
)

Description

A convenience wrapper around testthat::expect_snapshot() and expect_pkg_error_classes() that captures both the error class hierarchy and the user-facing message in a single snapshot.

Usage

expect_pkg_error_snapshot(
  object,
  package,
  ...,
  transform = NULL,
  variant = NULL,
  env = caller_env()
)

Arguments

Value

The result of testthat::expect_snapshot(), invisibly.

Description

When you use pkg_inform() to signal messages, you can use this function to test that those messages are generated as expected.

Usage

expect_pkg_message_classes(object, package, ...)

Arguments

Value

The message condition invisibly. Assignments made inside object (e.g. result <- fn_that_informs()) are visible to the caller after this function returns. Unlike most testthat expectations, this expectation cannot be usefully chained.

Examples

expect_pkg_message_classes(
  pkg_inform("stbl", "This is a test message", "test_subclass"),
  "stbl",
  "test_subclass"
)
try(
  expect_pkg_message_classes(
    pkg_inform("stbl", "This is a test message", "test_subclass"),
    "stbl",
    "different_subclass"
  )
)

Description

A convenience wrapper around testthat::expect_snapshot() and expect_pkg_message_classes() that captures both the message class hierarchy and the user-facing message in a single snapshot.

Usage

expect_pkg_message_snapshot(
  object,
  package,
  ...,
  transform = NULL,
  variant = NULL,
  env = caller_env()
)

Arguments

Value

The result of testthat::expect_snapshot(), invisibly.

Description

When you use pkg_warn() to signal warnings, you can use this function to test that those warnings are generated as expected.

Usage

expect_pkg_warning_classes(object, package, ...)

Arguments

Value

The warning condition invisibly. Assignments made inside object (e.g. result <- fn_that_warns()) are visible to the caller after this function returns. Unlike most testthat expectations, this expectation cannot be usefully chained.

Examples

expect_pkg_warning_classes(
  pkg_warn("stbl", "This is a test warning", "test_subclass"),
  "stbl",
  "test_subclass"
)
try(
  expect_pkg_warning_classes(
    pkg_warn("stbl", "This is a test warning", "test_subclass"),
    "stbl",
    "different_subclass"
  )
)

Description

A convenience wrapper around testthat::expect_snapshot() and expect_pkg_warning_classes() that captures both the warning class hierarchy and the user-facing message in a single snapshot.

Usage

expect_pkg_warning_snapshot(
  object,
  package,
  ...,
  transform = NULL,
  variant = NULL,
  env = caller_env()
)

Arguments

Value

The result of testthat::expect_snapshot(), invisibly.

Description

Silences a stbl error with the specified subclass. Other errors (including other stbl errors) are not caught and propagate normally. See the documentation of each ⁠stabilize_*()⁠ or ⁠to_*()⁠ function for the types of errors it throws.

Usage

ignore_stbl_error(expr, subclass = character())

Arguments

Value

The result of expr if no matching error is thrown, or NULL if a matching stbl error is caught.

Examples

ignore_stbl_error(to_chr(data.frame()), subclass = c("coerce", "character"))
ignore_stbl_error(to_chr("hello"), subclass = c("coerce", "character"))

# Omit subclass to catch any stbl error
ignore_stbl_error(to_chr(data.frame()))

Description

Returns an ordered set of strptime()-style format strings, used as the default value of accepted_datetime_formats in stabilize_date(), stabilize_dttm(), and their siblings. Character input is tried against each format in turn, in order, until one of them parses every element (see those functions for details).

Usage

locale_datetime_formats(locale_time = Sys.getlocale("LC_TIME"))

Arguments

Value

A character() vector of strptime()-style format strings, always starting with "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", and "%Y-%m-%d" (in that order), followed by the locale's conventional day/month order with "/" and then "-" separators (each listed with, then without, a " %H:%M:%S" suffix).

See Also

Other date functions: specify_date(), stabilize_date(), stabilize_date_scalar(), to(), to_date(), to_date_scalar()

Other datetime functions: specify_dttm(), stabilize_dttm(), stabilize_dttm_scalar(), to(), to_dttm(), to_dttm_scalar()

Examples

locale_datetime_formats("en_US.UTF-8")
locale_datetime_formats("en_GB.UTF-8")

Description

Extract the class (or type) of an object for use in error messages.

Usage

object_type(x)

Arguments

Value

A length-1 character vector describing the class of the object.

Examples

object_type("a")
object_type(1L)
object_type(1.1)
object_type(mtcars)
object_type(rlang::quo(something))

Description

A wrapper around cli::cli_abort() to throw classed errors, with an opinionated framework of error classes.

Usage

pkg_abort(
  package,
  message,
  subclass,
  call = caller_env(),
  message_env = call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Examples

try(pkg_abort("stbl", "This is a test error", "test_subclass"))
tryCatch(
  pkg_abort("stbl", "This is a test error", "test_subclass"),
  `stbl-error` = function(e) {
    "Caught a generic stbl error."
  }
)
tryCatch(
  pkg_abort("stbl", "This is a test error", "test_subclass"),
  `stbl-error-test_subclass` = function(e) {
    "Caught a specific subclass of stbl error."
  }
)

Description

A wrapper around cli::cli_inform() to throw classed messages, with an opinionated framework of message classes.

Usage

pkg_inform(
  package,
  message,
  subclass,
  call = caller_env(),
  message_env = call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Examples

pkg_inform("stbl", "This is a test message", "test_subclass")
withCallingHandlers(
  pkg_inform("stbl", "This is a test message", "test_subclass"),
  `stbl-message` = function(m) {
    message("Caught a generic stbl message.")
    invokeRestart("muffleMessage")
  }
)
withCallingHandlers(
  pkg_inform("stbl", "This is a test message", "test_subclass"),
  `stbl-message-test_subclass` = function(m) {
    message("Caught a specific subclass of stbl message.")
    invokeRestart("muffleMessage")
  }
)

Description

A wrapper around cli::cli_warn() to throw classed warnings, with an opinionated framework of warning classes.

Usage

pkg_warn(
  package,
  message,
  subclass,
  call = caller_env(),
  message_env = call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Examples

pkg_warn("stbl", "This is a test warning", "test_subclass")
withCallingHandlers(
  pkg_warn("stbl", "This is a test warning", "test_subclass"),
  `stbl-warning` = function(w) {
    message("Caught a generic stbl warning.")
    invokeRestart("muffleWarning")
  }
)
withCallingHandlers(
  pkg_warn("stbl", "This is a test warning", "test_subclass"),
  `stbl-warning-test_subclass` = function(w) {
    message("Caught a specific subclass of stbl warning.")
    invokeRestart("muffleWarning")
  }
)

Description

Attach a standardized error message to a regex pattern. By default, the message will be "must match the regex pattern {regex}". If the input regex has a negate attribute set to TRUE (set automatically by regex_must_not_match()), the message will instead be "must not match...". This message can be used with stabilize_chr() and stabilize_chr_scalar().

Usage

regex_must_match(regex)

regex_must_not_match(regex)

Arguments

Value

For regex_must_match, the regex value with names() equal to the generated error message.

For regex_must_not_match(), the regex value with a negate attribute and with names() equal to the generated "must not match" error message.

Examples

regex_must_match("[aeiou]")

# With negation:
regex <- "[aeiou]"
attr(regex, "negate") <- TRUE
regex_must_match(regex)
regex_must_not_match("[aeiou]")

Description

Catches a stbl error with the specified subclass and replaces its message with a new one. Use this to provide more context-specific error messages when calling stbl functions inside your own functions. See the documentation of each ⁠stabilize_*()⁠ or ⁠to_*()⁠ function for the types of errors it throws.

Usage

replace_stbl_error(
  expr,
  message,
  subclass = character(),
  additional_class = character(),
  message_env = caller_env()
)

Arguments

Value

The result of expr, or an error with the replacement message if a matching {stbl} error is thrown.

Examples

my_fn <- function(x) {
  x <- to_chr(x) |>
    replace_stbl_error(
      message = "{.arg x} must be a character vector of widgets",
      subclass = c("coerce", "character")
    )
}
try(my_fn(data.frame()))

# Specify a class to check for expected errors with testthat::expect_error()
my_fn2 <- function(x) {
  x <- to_chr(x) |>
    replace_stbl_error(
      message = "{.arg x} must be a character vector of widgets",
      subclass = c("coerce", "character"),
      additional_class = "mypkg-error-bad_widget"
    )
}
try(my_fn2(data.frame()))

# Omit subclass to catch any stbl error
my_fn3 <- function(x) {
  x <- to_chr(x) |>
    replace_stbl_error(message = "{.arg x} must be a character vector of widgets")
}
try(my_fn3(data.frame()))

Description

specify_all_of() creates a function that will call stabilize_all_of() with the provided specs. specify_all_of()'s function requires that x satisfy every provided spec, and that all specs agree on the coerced result.

Usage

specify_all_of(...)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_all_of() with the provided specs. The generated function will also accept ... for additional unnamed specs to pass to stabilize_all_of(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other specification functions: specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_a_then_b <- specify_all_of(
  specify_chr(regex = "^a"),
  specify_chr(regex = "b$")
)
stabilize_a_then_b("ab")
try(stabilize_a_then_b("ba"))

Description

specify_any_of() creates a function that will call stabilize_any_of() with the provided specs. specify_any_of()'s function tries each spec in order and returns the result of the first one that succeeds.

Usage

specify_any_of(...)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_any_of() with the provided specs. The generated function will also accept ... for additional unnamed specs to pass to stabilize_any_of(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other specification functions: specify_all_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_int_or_chr <- specify_any_of(specify_int(), specify_chr())
stabilize_int_or_chr(1L)
stabilize_int_or_chr("a")
try(stabilize_int_or_chr(TRUE))

Description

specify_chr() creates a function that will call stabilize_chr() with the provided arguments. specify_chr_scalar() creates a function that will call stabilize_chr_scalar() with the provided arguments. specify_character() is a synonym of specify_chr(), and specify_character_scalar() is a synonym of specify_chr_scalar().

Usage

specify_chr(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL
)

specify_chr_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL
)

specify_character(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL
)

specify_character_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_chr() or stabilize_chr_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_chr() or stabilize_chr_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other character functions: are_chr_ish(), stabilize_chr(), stabilize_chr_scalar(), to(), to_chr(), to_chr_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_email <- specify_chr(regex = "^[^@]+@[^@]+\\.[^@]+$")
stabilize_email("[email protected]")
try(stabilize_email("not-an-email-address"))

Description

specify_date() creates a function that will call stabilize_date() with the provided arguments. specify_date_scalar() creates a function that will call stabilize_date_scalar() with the provided arguments.

Usage

specify_date(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_date_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_date() or stabilize_date_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_date() or stabilize_date_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other date functions: locale_datetime_formats(), stabilize_date(), stabilize_date_scalar(), to(), to_date(), to_date_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_recent <- specify_date(min_value = "2000-01-01")
stabilize_recent("2024-01-01")
try(stabilize_recent("1999-12-31"))

Description

specify_dbl() creates a function that will call stabilize_dbl() with the provided arguments. specify_dbl_scalar() creates a function that will call stabilize_dbl_scalar() with the provided arguments. specify_double() is a synonym of specify_dbl(), and specify_double_scalar() is a synonym of specify_dbl_scalar().

Usage

specify_dbl(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_dbl_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_double(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_double_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_dbl() or stabilize_dbl_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_dbl() or stabilize_dbl_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other double functions: are_dbl_ish(), stabilize_dbl(), stabilize_dbl_scalar(), to(), to_dbl(), to_dbl_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_3_to_5 <- specify_dbl(min_value = 3, max_value = 5)
stabilize_3_to_5(c(3.3, 4.4, 5))
try(stabilize_3_to_5(c(1:6)))

Description

specify_df() creates a function that will call stabilize_df() with the provided arguments. specify_data_frame() is a synonym of specify_df().

Usage

specify_df(
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .required = ...names()
)

specify_data_frame(
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .required = ...names()
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_df() with the provided arguments. The generated function will also accept ... for additional named column specifications to pass to stabilize_df(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other data frame functions: stabilize_df(), to(), to_df()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_person_df <- specify_df(
  name = specify_chr_scalar(allow_na = FALSE),
  age = specify_int_scalar(allow_na = FALSE),
  .extra_cols = assert_present
)
stabilize_person_df(data.frame(name = "Alice", age = 30L, score = 99.5))
try(stabilize_person_df(data.frame(name = "Alice")))

# Mark a column as optional via .required
stabilize_person_df2 <- specify_df(
  name = specify_chr_scalar(allow_na = FALSE),
  age = specify_int_scalar(allow_na = FALSE),
  .required = "name"
)
stabilize_person_df2(data.frame(name = "Alice"))

Description

specify_dttm() creates a function that will call stabilize_dttm() with the provided arguments. specify_dttm_scalar() creates a function that will call stabilize_dttm_scalar() with the provided arguments. specify_datetime() is a synonym of specify_dttm(), and specify_datetime_scalar() is a synonym of specify_dttm_scalar().

Usage

specify_dttm(
  tz = "UTC",
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_dttm_scalar(
  tz = "UTC",
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_datetime(
  tz = "UTC",
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_datetime_scalar(
  tz = "UTC",
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_dttm() or stabilize_dttm_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_dttm() or stabilize_dttm_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other datetime functions: locale_datetime_formats(), stabilize_dttm(), stabilize_dttm_scalar(), to(), to_dttm(), to_dttm_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_recent <- specify_dttm(min_value = "2000-01-01T00:00:00Z")
stabilize_recent("2024-01-01T00:00:00Z")
try(stabilize_recent("1999-12-31T00:00:00Z"))

Description

specify_dur() creates a function that will call stabilize_dur() with the provided arguments. specify_dur_scalar() creates a function that will call stabilize_dur_scalar() with the provided arguments. specify_duration() is a synonym of specify_dur(), and specify_duration_scalar() is a synonym of specify_dur_scalar().

Usage

specify_dur(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

specify_dur_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

specify_duration(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

specify_duration_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_dur() or stabilize_dur_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_dur() or stabilize_dur_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other duration functions: stabilize_dur(), stabilize_dur_scalar(), to(), to_dur(), to_dur_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_short <- specify_dur(max_value = "P1D")
stabilize_short("PT12H")
try(stabilize_short("P2D"))

Description

specify_each() creates a function that will call stabilize_each() with the provided spec, letting an element-wise spec be reused and nested inside other ⁠specify_*()⁠/⁠stabilize_*()⁠ calls.

Usage

specify_each(spec)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_each() with the provided spec. The generated function will also accept simplify and ... to pass to stabilize_each(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_ints <- specify_each(stabilize_int)
stabilize_ints(list("1", "2", "3"))
try(stabilize_ints(list("1", "a")))

Description

specify_fct() creates a function that will call stabilize_fct() with the provided arguments. specify_fct_scalar() creates a function that will call stabilize_fct_scalar() with the provided arguments. specify_factor() is a synonym of specify_fct(), and specify_factor_scalar() is a synonym of specify_fct_scalar().

Usage

specify_fct(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  ordered = FALSE,
  to_na = character()
)

specify_fct_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  ordered = FALSE,
  to_na = character()
)

specify_factor(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  ordered = FALSE,
  to_na = character()
)

specify_factor_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  ordered = FALSE,
  to_na = character()
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_fct() or stabilize_fct_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_fct() or stabilize_fct_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other factor functions: are_fct_ish(), stabilize_fct(), stabilize_fct_scalar(), to(), to_fct(), to_fct_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_lowercase_letter <- specify_fct(levels = letters)
stabilize_lowercase_letter(c("s", "t", "b", "l"))
try(stabilize_lowercase_letter("A"))

Description

specify_int() creates a function that will call stabilize_int() with the provided arguments. specify_int_scalar() creates a function that will call stabilize_int_scalar() with the provided arguments. specify_integer() is a synonym of specify_int(), and specify_integer_scalar() is a synonym of specify_int_scalar().

Usage

specify_int(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_int_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_integer(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

specify_integer_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  exclusive_min_value = NULL,
  exclusive_max_value = NULL,
  allowed_values = NULL,
  multiple_of = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_int() or stabilize_int_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_int() or stabilize_int_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other integer functions: are_int_ish(), stabilize_int(), stabilize_int_scalar(), to(), to_int(), to_int_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_3_to_5 <- specify_int(min_value = 3, max_value = 5)
stabilize_3_to_5(c(3:5))
try(stabilize_3_to_5(c(1:6)))

Description

specify_lgl() creates a function that will call stabilize_lgl() with the provided arguments. specify_lgl_scalar() creates a function that will call stabilize_lgl_scalar() with the provided arguments. specify_logical() is a synonym of specify_lgl(), and specify_logical_scalar() is a synonym of specify_lgl_scalar().

Usage

specify_lgl(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  allowed_values = NULL
)

specify_lgl_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  allowed_values = NULL
)

specify_logical(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  allowed_values = NULL
)

specify_logical_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  allowed_values = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_lgl() or stabilize_lgl_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_lgl() or stabilize_lgl_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other logical functions: are_lgl_ish(), stabilize_lgl(), stabilize_lgl_scalar(), to(), to_lgl(), to_lgl_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_few_lgl <- specify_lgl(max_size = 5)
stabilize_few_lgl(c(TRUE, "False", TRUE))
try(stabilize_few_lgl(rep(TRUE, 10)))

Description

specify_lst() creates a function that will call stabilize_lst() with the provided arguments. specify_list() is a synonym of specify_lst().

Usage

specify_lst(
  ...,
  .named = NULL,
  .unnamed = NULL,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names()
)

specify_list(
  ...,
  .named = NULL,
  .unnamed = NULL,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names()
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_lst() with the provided arguments. The generated function will also accept ... for additional named element specifications to pass to stabilize_lst(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other list functions: assert_present(), stabilize_lst(), to(), to_lst()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_one_of(), specify_time()

Examples

stabilize_config <- specify_lst(
  name = specify_chr_scalar(allow_na = FALSE),
  version = stabilize_int_scalar,
  debug = specify_lgl_scalar(allow_na = FALSE),
  .unnamed = stabilize_chr_scalar
)
stabilize_config(list(name = "myapp", version = 1L, debug = FALSE, "extra"))
try(
  stabilize_config(
    list(name = "myapp", version = 1L, debug = FALSE, c("a", "b"))
  )
)

# Mark some elements as optional via .required
stabilize_settings <- specify_lst(
  name = specify_chr_scalar(),
  nickname = specify_chr_scalar(),
  .required = "name"
)
stabilize_settings(list(name = "Alice"))

Description

specify_one_of() creates a function that will call stabilize_one_of() with the provided specs. specify_one_of()'s function requires that exactly one of the provided specs succeeds.

Usage

specify_one_of(...)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_one_of() with the provided specs. The generated function will also accept ... for additional unnamed specs to pass to stabilize_one_of(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_time()

Examples

stabilize_int_xor_chr <- specify_one_of(stabilize_int, stabilize_chr)
stabilize_int_xor_chr("a")
try(stabilize_int_xor_chr("1"))

Description

specify_time() creates a function that will call stabilize_time() with the provided arguments. specify_time_scalar() creates a function that will call stabilize_time_scalar() with the provided arguments.

Usage

specify_time(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

specify_time_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL
)

Arguments

Value

A function of class "stbl_specified_fn" that calls stabilize_time() or stabilize_time_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_time() or stabilize_time_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See Also

Other time functions: stabilize_time(), stabilize_time_scalar(), to(), to_time(), to_time_scalar()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of()

Examples

stabilize_afternoon <- specify_time(min_value = "12:00:00Z")
stabilize_afternoon("13:00:00Z")
try(stabilize_afternoon("06:00:00Z"))

Description

stabilize_all_of() validates and coerces x by applying every function in ... to x, independently. x must satisfy every spec, and all specs must agree on the coerced result; if any spec fails, or specs disagree on the coerced value, an informative error is thrown. stabilise_all_of() is a synonym.

Usage

stabilize_all_of(
  x,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_all_of(
  x,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x coerced or validated by every function in ..., or an error condition with classes ⁠<stbl-error>⁠, ⁠<stbl-condition>⁠, ⁠<rlang_error>⁠, ⁠<error>⁠, ⁠<condition>⁠, and a specific class by failure mode:

• ⁠<stbl-error-empty_specs>⁠ when no functions are supplied in ....

• ⁠<stbl-error-named_spec>⁠ when any element of ... is named.

• ⁠<stbl-error-cant_stabilize_all_of>⁠ when any provided function fails.

• ⁠<stbl-error-inconsistent_all_of>⁠ when every function succeeds, but they don't all produce the same coerced value.

See Also

Other stabilization functions: assert_contains(), assert_not(), assert_present(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

# Returns x unchanged when all functions succeed
stabilize_all_of(1L, stabilize_int, stabilize_int_scalar)

# Each spec is applied to the original x, independently
stabilize_all_of("ab", specify_chr(regex = "^a"), specify_chr(regex = "b$"))

# Errors with a combined message when a spec fails
try(stabilize_all_of("a", stabilize_int, stabilize_chr))

# Errors because each spec sees the original "1" (a string); the second
# spec would succeed on 1L, but doesn't get the chance to see it
try(stabilize_all_of("1", stabilize_int, specify_dbl(coerce_character = FALSE)))

# Errors when specs succeed but disagree on the coerced value
# (stabilize_int() keeps 1L an integer; specify_dbl() makes it a double)
try(stabilize_all_of(1L, stabilize_int, specify_dbl()))

Description

stabilize_any_of() attempts to validate and coerce x using each function in ... in order. It returns the result of the first function that succeeds. If all functions fail, an informative error that combines the individual failure messages is thrown. stabilise_any_of() is a synonym.

to_any_of() is analogous to to(): it tries to coerce x to each type given in ... (as a prototype such as integer() or character()) and returns the first successful result.

Usage

stabilize_any_of(
  x,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_any_of(
  x,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_any_of(
  x,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x coerced or validated by the first successful function or prototype in ..., or an error condition with classes ⁠<stbl-error>⁠, ⁠<stbl-condition>⁠, ⁠<rlang_error>⁠, ⁠<error>⁠, ⁠<condition>⁠, and a specific class by failure mode:

• ⁠<stbl-error-empty_specs>⁠ when no functions are supplied in ....

• ⁠<stbl-error-named_spec>⁠ when any element of ... is named.

• ⁠<stbl-error-cant_stabilize_any_of>⁠ when all provided functions fail.

See Also

Other stabilization functions: assert_contains(), assert_not(), assert_present(), stabilize_all_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

# Returns x unchanged when the first function succeeds
stabilize_any_of(1L, stabilize_int, stabilize_chr)

# Falls through to stabilize_chr when stabilize_int fails
stabilize_any_of("a", stabilize_int, stabilize_chr)

# Coerces via the first matching function ("1" -> 1L)
stabilize_any_of("1", stabilize_int, stabilize_chr)

# A mixed list falls through to stabilize_chr because "a" can't be integer
stabilize_any_of(list(1L, "a"), stabilize_int, stabilize_chr)

# Errors with a combined message when all functions fail
try(stabilize_any_of(list(1, TRUE, "23", "maybe"), stabilize_lgl, stabilize_int))
# to_any_of() uses prototypes instead of functions
to_any_of(1L, integer(), character())
to_any_of("a", integer(), character())
to_any_of("1", integer(), character())
try(to_any_of(list(), integer(), character()))

Description

stabilize_arg() is used by other functions such as stabilize_int(). Use stabilize_arg() if the type-specific functions will not work for your use case, but you would still like to check things like size or whether the object is NULL.

stabilize_arg_scalar() is optimized to check for length-1 vectors.

Usage

stabilize_arg(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_arg_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  allow_na = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x, or an error condition with classes ⁠<stbl-error>⁠, ⁠<stbl-condition>⁠, ⁠<rlang_error>⁠, ⁠<error>⁠, ⁠<condition>⁠, and a specific class by failure mode:

• ⁠<stbl-error-bad_null>⁠ for NULL values when allow_null = FALSE.

• ⁠<stbl-error-bad_na>⁠ for NA values when allow_na = FALSE.

• ⁠<stbl-error-size_too_small>⁠ when the vector is shorter than min_size.

• ⁠<stbl-error-size_too_large>⁠ when the vector is longer than max_size.

• ⁠<stbl-error-bad_empty>⁠ for empty vectors when allow_zero_length = FALSE in stabilize_arg_scalar().

• ⁠<stbl-error-non_scalar>⁠ for non-scalar vectors in stabilize_arg_scalar().

See Also

Other stabilization functions: assert_contains(), assert_not(), assert_present(), stabilize_all_of(), stabilize_any_of(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

wrapper <- function(this_arg, ...) {
  stabilize_arg(this_arg, ...)
}
wrapper(1)
wrapper(NULL)
wrapper(NA)
try(wrapper(NULL, allow_null = FALSE))
try(wrapper(NA, allow_na = FALSE))
try(wrapper(1, min_size = 2))
try(wrapper(1:10, max_size = 5))
stabilize_arg_scalar("a")
stabilize_arg_scalar(1L)
try(stabilize_arg_scalar(1:10))

Description

Compared to to_chr(), stabilize_chr() checks more details, but is slower. stabilise_chr(), stabilize_character(), and stabilise_character() are synonyms of stabilize_chr().

Usage

stabilize_chr(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_character(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_chr(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_character(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_characters = NULL,
  max_characters = NULL,
  regex = NULL,
  allowed_values = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)