Package {stbl}

Title:	Stabilize Function Arguments
Version:	0.4.0
Description:	A set of consistent, opinionated functions to quickly check function arguments, coerce them to the desired configuration, or deliver informative error messages when that is not possible.
License:	MIT + file LICENSE
URL:	https://stbl.wrangle.zone/, https://github.com/wranglezone/stbl
BugReports:	https://github.com/wranglezone/stbl/issues
Depends:	R (≥ 4.1)
Imports:	cli (≥ 3.4.0), glue, rlang (≥ 1.0.3), vctrs
Suggests:	covr, knitr, rmarkdown, stringi, stringr, testthat (≥ 3.3.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/testthat/parallel:	true
Config/Needs/website:	quarto
Encoding:	UTF-8
Language:	en-US
NeedsCompilation:	yes
Config/roxygen2/version:	8.0.0
Packaged:	2026-07-28 13:39:00 UTC; jonth
Author:	Jon Harmon [aut, cre, cph]
Maintainer:	Jon Harmon <jonthegeek@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-28 14:10:02 UTC

stbl: Stabilize Function Arguments

Description

A set of consistent, opinionated functions to quickly check function arguments, coerce them to the desired configuration, or deliver informative error messages when that is not possible.

Author(s)

Maintainer: Jon Harmon jonthegeek@gmail.com (ORCID) [copyright holder]

Authors:

• Jon Harmon jonthegeek@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://stbl.wrangle.zone/

• https://github.com/wranglezone/stbl

• Report bugs at https://github.com/wranglezone/stbl/issues

NULL-coalescing-like operator

Description

If the left-hand side is not NULL, returns the right-hand side. Otherwise, returns NULL. This is useful for guarding expressions that should only be executed if a value is not NULL. Meant to be similar to the ⁠%||%⁠ operator (which returns y if x is NULL).

Usage

x %&&% y

Arguments

Value

NULL or the value of y.

Apply a single regex rule to a character vector

Description

Apply a single regex rule to a character vector

Usage

.apply_regex_rule(rule, x, x_arg, call)

Arguments

Value

A character vector of error messages if the rule fails, otherwise NULL.

Check for values that would be lost during factor coercion

Description

Check for values that would be lost during factor coercion

Usage

.are_not_fct_ish_chr(x, levels, to_na = character())

Arguments

Value

A logical vector where TRUE indicates a failure.

Call a spec function with properly-named context arguments

Description

Call a spec function with properly-named context arguments

Usage

.call_specified_fn(spec_fn, .x, .x_arg, .call)

Arguments

Value

The validated value.

Capture the first condition thrown by an expression

Description

Capture the first condition thrown by an expression

Usage

.capture_first_pkg_condition(obj_expr, condition_name, muffle_restart, env)

Arguments

Value

The first matching condition invisibly, or NULL if none signalled.

Check that all list elements are named

Description

Check that all list elements are named

Usage

.check_all_named(x, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL invisibly (called for side effects).

Check for coercion failures and stop if any are found

Description

Check for coercion failures and stop if any are found

Usage

.check_cast_failures(failures, x_class, to, due_to, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Check for character to integer coercion failures

Description

Check for character to integer coercion failures

Usage

.check_chr_to_int_failures(res, x_class, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Check for complex to integer coercion failures

Description

Check for complex to integer coercion failures

Usage

.check_cpx_to_int_failures(res, x_class, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Check for double to integer coercion failures

Description

Check for double to integer coercion failures

Usage

.check_dbl_to_int_failures(res, x_class, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Check that required column names are present in a data frame

Description

Check that required column names are present in a data frame

Usage

.check_df_col_names(.x, col_names, x_arg, call)

Arguments

Value

NULL, invisibly, if the check passes.

Check that a data frame has an acceptable number of rows

Description

Check that a data frame has an acceptable number of rows

Usage

.check_df_rows(.x, min_rows, max_rows, x_arg, call)

Arguments

Value

NULL, invisibly, if the check passes.

Check for duplicate names in a list

Description

Check for duplicate names in a list

Usage

.check_duplicate_names(.x, .allow_duplicate_names, .x_arg, .call)

Arguments

Value

NULL, invisibly, if the check passes.

Check whether functions are allowed

Description

Check whether functions are allowed

Usage

.check_function_allowed(
  x,
  coerce_function = FALSE,
  x_arg = caller_arg(x),
  call = caller_env()
)

Arguments

Value

NULL invisibly (called for side effects).

Error if an object is a primitive function

Description

Error if an object is a primitive function

Usage

.check_is_not_primitive(x, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL invisibly (called for side effects).

Check list coercion failures and error if any element could not be converted

Description

Check list coercion failures and error if any element could not be converted

Usage

.check_lst_failures(valid, to_class, x_class, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Check for NA values

Description

Check for NA values

Usage

.check_na(x, allow_na = TRUE, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL invisibly (called for side effects).

Check that list elements do not have jagged (unequal non-1) lengths

Description

Check that list elements do not have jagged (unequal non-1) lengths

Usage

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

Arguments

Value

NULL invisibly (called for side effects).

Check if an object is a scalar

Description

Check if an object is a scalar

Usage

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

Arguments

Value

NULL invisibly (called for side effects).

Check the size of an object

Description

Check the size of an object

Usage

.check_size(x, min_size, max_size, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL invisibly (called for side effects).

Check that all elements of a spec list are named

Description

Check that all elements of a spec list are named

Usage

.check_specs_named(..., .call = caller_env())

Arguments

Value

NULL, invisibly, if all elements are named.

Check character values against one or more regex patterns

Description

Check character values against one or more regex patterns

Usage

.check_value_chr(x, regex, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL, invisibly, if x passes all checks.

Check double values against min and max values

Description

Check double values against min and max values

Usage

.check_value_dbl(
  x,
  min_value,
  max_value,
  x_arg = caller_arg(x),
  call = caller_env()
)

Arguments

Value

NULL, invisibly, if x passes all checks.

Check that one value is not greater than another

Description

Check that one value is not greater than another

Usage

.check_x_no_more_than_y(
  x,
  y,
  x_arg = caller_arg(x),
  y_arg = caller_arg(y),
  call = caller_env()
)

Arguments

Value

NULL invisibly (called for side effects).

Call the C routine to convert a vector to another type

Description

Call the C routine to convert a vector to another type

Usage

.chr_are_fnish(x)

.chr_to_fn(x, definition_env = rlang::global_env())

.chr_to_lgl(x)

.chr_to_int(x)

.chr_to_dbl(x)

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

.dbl_to_chr(x)

.dbl_are_chrish(x)

.dbl_to_int(x)

.dbl_to_lgl(x)

.dbl_are_lglish(x)

.int_to_chr(x)

.int_are_chrish(x)

.int_to_fct(x, to = NULL, ordered = FALSE)

.int_to_dbl(x)

.int_are_dblish(x)

.lgl_to_chr(x)

.lgl_are_chrish(x)

.lgl_to_dbl(x)

.lgl_to_int(x)

.lgl_are_dblish(x)

.lgl_are_intish(x)

.cpx_to_dbl(x)

.cpx_to_int(x)

.fct_to_chr(x)

.fct_are_chrish(x)

.fct_to_dbl(x)

.fct_to_int(x)

.fct_to_lgl(x)

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

.lst_to_dbl(x)

.lst_to_int(x)

.lst_to_lgl(x)

.lst_to_chr(x)

.lst_to_fct(x)

.stbl_to(x, to)

.check_min_dbl(x, min_val)

.check_max_dbl(x, max_val)

Arguments

Value

.x_to_y(): A list with two elements: result, the converted vector, and valid, a logical vector indicating whether each element was successfully coerced without losing information. .x_are_yish(): A logical vector indicating whether each element of x can be coerced to the target type. .check_min_dbl() and .check_max_dbl(): NULL if all values pass the check, otherwise a vector of failing indices.

Return the name of a function

Description

Return the name of a function

Usage

.chr_from_fn_sym(x, x_name)

Arguments

Value

A length-1 character string.

Build a string from a :: or ::: call expression

Description

Build a string from a :: or ::: call expression

Usage

.chr_from_op_call(x_expr)

Arguments

Value

A length-1 character string, e.g. "base::mean".

Escape curly braces for safe printing with cli

Description

Escape curly braces for safe printing with cli

Usage

.cli_escape(msg)

Arguments

Value

The messages with curly braces escaped.

Wrap text in cli markup

Description

Wrap text in cli markup

Usage

.cli_mark(x, tag)

Arguments

Value

A character vector the same length as x with cli markup.

Coerce to factor with specified levels

Description

Coerce to factor with specified levels

Usage

.coerce_fct_levels(
  x,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env()
)

Arguments

Value

x as a factor with specified levels and NAs.

Core implementation for applying factor levels

Description

Core implementation for applying factor levels

Usage

.coerce_fct_levels_impl(
  x,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env()
)

Arguments

Value

x as a factor with the specified levels.

Coerce specified values to NA

Description

Coerce specified values to NA

Usage

.coerce_fct_to_na(x, to_na = character(), call = caller_env())

Arguments

Value

x with specified values converted to NA.

Paste together collapsing with -

Description

Paste together collapsing with -

Usage

.collapse_dash(...)

Arguments

Value

A length-1 character vector.

Paste together with - separator

Description

Paste together with - separator

Usage

.compile_dash(...)

Arguments

Value

A length-1 character vector.

Compile a condition class chain

Description

Compile a condition class chain

Usage

.compile_pkg_condition_classes(package, ...)

Arguments

Value

A character vector.

Compile an error class chain

Description

Compile an error class chain

Usage

.compile_pkg_error_classes(package, ...)

Arguments

Value

A character vector of classes.

Compile a message class chain

Description

Compile a message class chain

Usage

.compile_pkg_message_classes(package, ...)

Arguments

Value

A character vector of classes.

Compile a warning class chain

Description

Compile a warning class chain

Usage

.compile_pkg_warning_classes(package, ...)

Arguments

Value

A character vector of classes.

Construct a specified stabilizer function

Description

Construct a specified stabilizer function

Usage

.construct_specification_fn(
  check_dupes,
  stabilizer,
  factory_args,
  ...,
  call = rlang::caller_env()
)

Arguments

Value

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

Assemble the function name of the stabilizer

Description

Assemble the function name of the stabilizer

Usage

.construct_stabilizer_symbol(stabilizer, scalar = FALSE)

Arguments

Value

The symbol of the stabilizer function to call.

Define the main error message for a "must" error

Description

Define the main error message for a "must" error

Usage

.define_main_msg(x_arg, msg)

Arguments

Value

A character string.

Describe a character-based validation failure

Description

Describe a character-based validation failure

Usage

.describe_failure_chr(x, success, negate = FALSE)

Arguments

Value

A named character vector to be used as additional_msg in .stop_must().

Describe a numeric value validation failure

Description

Describe a numeric value validation failure

Usage

.describe_failure_dbl_value(
  x,
  failure_locations,
  direction,
  target_value,
  x_arg
)

Arguments

Value

A named character vector for .stbl_abort().

Describe multiple numeric value failures

Description

Describe multiple numeric value failures

Usage

.describe_failure_dbl_value_multi(x, msg_main, failure_locations, direction)

Arguments

Value

A named character vector.

Describe a single numeric value failure

Description

Describe a single numeric value failure

Usage

.describe_failure_dbl_value_single(x, msg_main, direction)

Arguments

Value

A named character vector.

Check if all elements of a list-like object are ish

Description

Check if all elements of a list-like object are ish

Usage

.elements_are_cls_ish(x, are_cls_ish_fn, ...)

Arguments

Snapshot-test a package condition

Description

Snapshot-test a package condition

Usage

.expect_pkg_condition_snapshot(
  obj_expr,
  package,
  class_components,
  expect_fn_name,
  expect_fn,
  check_installed_msg,
  transform,
  variant,
  env
)

Arguments

Value

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

Force slow path in .to_cls_scalar()

Description

Force slow path in .to_cls_scalar()

Usage

.fast_false(x)

Arguments

Value

FALSE, always.

Safely find failure locations in a vector

Description

Safely find failure locations in a vector

Usage

.find_failures(x, check_value, check_fn)

Arguments

Value

An integer vector of failure locations, or NULL if there are no failures or the check is skipped.

A wrapper for glue::glue with bracket delimiters

Description

A wrapper for glue::glue with bracket delimiters

Usage

.glue2(..., env = caller_env())

Arguments

Value

A character string with evaluated expressions.

Detect a regex pattern in a character vector

Description

Detect a regex pattern in a character vector

Usage

.has_regex_pattern(x, regex)

Arguments

Value

A logical vector of matches in x to regex.

Check if a value is NULL and NULLs are allowed

Description

Check if a value is NULL and NULLs are allowed

Usage

.is_allowed_null(x, allow_null = TRUE, call = caller_env())

Arguments

Value

⁠(length-1 logical)⁠ TRUE if x is NULL and allow_null is TRUE, else FALSE.

Check if an expression is a covr counter call

Description

covr instruments code by wrapping expressions in if (TRUE) { covr:::count(key); original } blocks. This checks whether expr is the covr:::count(key) part.

Usage

.is_covr_count_call(expr)

Arguments

Value

TRUE if expr is a covr counter call, FALSE otherwise.

Construct the check_dupes expression

Description

Construct the check_dupes expression

Usage

.maybe_check_dupes(factory_args)

Arguments

Value

An empty list, or a list containing an expression that checks for duplicate arguments.

Return a package-qualified name if the name resolves to the same function

Description

Return a package-qualified name if the name resolves to the same function

Usage

.maybe_qualify_fn_name(fn, fn_env, x_name)

Arguments

Value

"pkg::x_name" if x_name resolves to fn in fn_env, otherwise x_name.

Check if two functions have the same definition

Description

Check if two functions have the same definition

Usage

.same_fn(x, y)

Arguments

Value

TRUE if the functions are the same, FALSE otherwise.

Shared parameters

Description

These parameters are used in multiple functions. They are defined here to make them easier to import and to find.

Arguments

Shared parameters for check functions

Description

Shared parameters for check functions

Arguments

Shared params for list helpers

Description

Shared params for list helpers

Arguments

Shared return for condition functions

Description

Shared return for condition functions

Value

NULL invisibly (called for side effects).

Stabilize an object of a specific class

Description

Stabilize an object of a specific class

Usage

.stabilize_cls(
  x,
  to_cls_fn,
  ...,
  to_cls_args = list(),
  check_cls_value_fn = NULL,
  check_cls_value_fn_args = list(),
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x as a vector of the target class with all checks passed.

Stabilize a scalar object of a specific class

Description

Stabilize a scalar object of a specific class

Usage

.stabilize_cls_scalar(
  x,
  to_cls_scalar_fn,
  ...,
  to_cls_scalar_args = list(),
  check_cls_value_fn = NULL,
  check_cls_value_fn_args = list(),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x as a scalar of the target class with all checks passed.

Signal an error with standards applied

Description

Signal an error with standards applied

Usage

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

Arguments

Value

NULL invisibly (called for side effects).

Signal a message with standards applied

Description

Signal a message with standards applied

Usage

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

Arguments

Value

NULL invisibly (called for side effects).

Signal a warning with standards applied

Description

Signal a warning with standards applied

Usage

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

Arguments

Value

NULL invisibly (called for side effects).

Stop for bad factor levels

Description

Stop for bad factor levels

Usage

.stop_bad_levels(x, bad_casts, levels, to_na, x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Abort with a standardized "can't coerce" message

Description

Abort with a standardized "can't coerce" message

Usage

.stop_cant_coerce(
  from_class,
  to_class,
  x_arg,
  call,
  additional_msg = NULL,
  message_env = call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Abort because an argument must not be a function

Description

Abort because an argument must not be a function

Usage

.stop_function(x_arg, call)

Arguments

Value

NULL invisibly (called for side effects).

Error if a function expression is anonymous (not a symbol)

Description

Error if a function expression is anonymous (not a symbol)

Usage

.stop_if_anon_fn(x_expr, x_class, x_arg, call)

Arguments

Abort with an "incompatible type" message

Description

Abort with an "incompatible type" message

Usage

.stop_incompatible(
  x_class,
  to,
  failures,
  due_to,
  x_arg,
  call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Abort with a standardized "must" message

Description

Abort with a standardized "must" message

Usage

.stop_must(
  msg,
  x_arg,
  call,
  additional_msg = NULL,
  subclass = "must",
  message_env = call,
  parent = NULL,
  ...
)

Arguments

Value

NULL invisibly (called for side effects).

Abort because an argument must not be NULL

Description

Abort because an argument must not be NULL

Usage

.stop_null(x_arg, call, parent = NULL, ...)

Arguments

Value

NULL invisibly (called for side effects).

Strip covr counter wrappers from an expression

Description

covr instruments code for coverage by wrapping expressions in if (TRUE) { covr:::count(key); original } blocks. This function recursively removes those wrappers so that snapshotted code remains stable across normal and coverage runs.

Usage

.strip_covr_from_expr(expr)

Arguments

Value

The expression with all covr counter blocks removed.

Internal S3 implementation of to_chr

Description

Internal S3 implementation of to_chr

Usage

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

Arguments

Value

The argument coerced to character.

Coerce an object from a factor to a specific class

Description

Coerce an object from a factor to a specific class

Usage

.to_cls_from_fct(
  x,
  to_cls_fn,
  to_cls_args,
  to_class,
  coerce_factor = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x coerced to the target class.

Coerce an object to a specific scalar class

Description

Coerce an object to a specific scalar class

Usage

.to_cls_scalar(
  x,
  is_rlang_cls_scalar,
  to_cls_fn,
  to_cls_args = list(),
  allow_null = TRUE,
  allow_zero_length = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x as a scalar of the target class.

Coerce a vector to a one-column data frame

Description

Coerce a vector to a one-column data frame

Usage

.to_df_vector(x, x_expr, x_arg, call, x_class, ...)

Arguments

Value

A one-column data frame.

Ensure an argument is NULL

Description

Ensure an argument is NULL

Usage

.to_null(x, allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

NULL or an error.

Coerce an object from a complex to a numeric class

Description

Coerce an object from a complex to a numeric class

Usage

.to_num_from_complex(
  x,
  cast_fn,
  to_type_obj,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x coerced to the target class.

Validate or reject extra named elements

Description

Validate or reject extra named elements

Usage

.validate_extra_named_elements(
  .x,
  nms,
  is_extra_named,
  named_spec,
  .x_arg,
  .call
)

Arguments

Value

The updated list.

Validate all named elements (required and extra)

Description

Validate all named elements (required and extra)

Usage

.validate_named_elements(
  .x,
  ...,
  .named,
  .allow_duplicate_names,
  .x_arg,
  .call
)

Arguments

Value

The updated list.

Validate required named elements against their spec functions

Description

Validate required named elements against their spec functions

Usage

.validate_required_elements(.x, element_specs, nms, .x_arg, .call)

Arguments

Value

The updated list.

Validate or reject unnamed elements

Description

Validate or reject unnamed elements

Usage

.validate_unnamed_elements(.x, .unnamed, .x_arg, .call)

Arguments

Value

The updated list.

Check if an object can be safely coerced to character

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(), to()

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)))

Check if an object can be safely coerced to double

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(), to()

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))

Check if an object can be safely coerced to a factor

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(), to()

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"))

Check if an object can be safely coerced to a function

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)

Check if an object can be safely coerced to integer

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(), to()

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")))

Check if an object can be safely coerced to logical

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(), to()

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"))

Test package error classes

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"
  )
)

Snapshot-test a package error

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.

Test package message classes

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"
  )
)

Snapshot-test a package message

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.

Test package warning classes

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"
  )
)

Snapshot-test a package warning

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.

Injection operator for defused arguments

Description

Injection operator for defused arguments

Identify the class, type, etc of an object

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))

Signal an error with standards applied

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."
  }
)

Signal a message with standards applied

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")
  }
)

Signal a warning with standards applied

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")
  }
)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

rlang

caller_arg(), caller_env()

Create a regex matching rule

Description

Attach a standardized error message to a regex argument. 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]")

Create a specified character stabilizer function

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,
  regex = NULL
)

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

specify_character(
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  regex = NULL
)

specify_character_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  regex = 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(), to()

Other specification functions: specify_dbl(), specify_df(), specify_fct(), specify_int(), specify_lgl(), specify_lst()

Examples

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

Create a specified stabilizer function

Description

Create a specified stabilizer function

Usage

specify_cls(
  stabilizer,
  factory_args = list(),
  scalar = FALSE,
  call = rlang::caller_env()
)

Arguments

Value

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

Create a specified double stabilizer function

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,
  min_value = NULL,
  max_value = 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
)

specify_double(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = 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
)

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(), to()

Other specification functions: specify_chr(), specify_df(), specify_fct(), specify_int(), specify_lgl(), specify_lst()

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)))

Create a specified data frame stabilizer function

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
)

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

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_chr(), specify_dbl(), specify_fct(), specify_int(), specify_lgl(), specify_lst()

Examples

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

Create a specified factor stabilizer function

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,
  to_na = character()
)

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

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

specify_factor_scalar(
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  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(), to()

Other specification functions: specify_chr(), specify_dbl(), specify_df(), specify_int(), specify_lgl(), specify_lst()

Examples

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

Create a specified integer stabilizer function

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,
  min_value = NULL,
  max_value = 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
)

specify_integer(
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = 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
)

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(), to()

Other specification functions: specify_chr(), specify_dbl(), specify_df(), specify_fct(), specify_lgl(), specify_lst()

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)))

Create a specified logical stabilizer function

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
)

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

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

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

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(), to()

Other specification functions: specify_chr(), specify_dbl(), specify_df(), specify_fct(), specify_int(), specify_lst()

Examples

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

Create a specified list stabilizer function

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,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL
)

specify_list(
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL
)

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: stabilize_lst(), stabilize_present(), to(), to_lst()

Other specification functions: specify_chr(), specify_dbl(), specify_df(), specify_fct(), specify_int(), specify_lgl()

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"))
  )
)

Ensure an argument meets expectations

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 argument 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,
  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, unless one of the checks fails.

See Also

Other stabilization functions: stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_lst(), stabilize_present()

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))

Ensure a character argument meets expectations

Description

to_chr() checks whether an argument can be coerced to character without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_character is a synonym of to_chr().

stabilize_chr() can check more details about the argument, but is slower than to_chr(). stabilise_chr(), stabilize_character(), and stabilise_character() are synonyms of stabilize_chr().

stabilize_chr_scalar() and to_chr_scalar() are optimized to check for length-1 character vectors. stabilise_chr_scalar, stabilize_character_scalar(), and stabilise_character_scalar are synonyms of stabilize_chr_scalar(), and to_character_scalar() is a synonym of to_chr_scalar().

Usage

stabilize_chr(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  regex = 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,
  regex = 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,
  regex = 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,
  regex = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_chr_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  regex = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_character_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  regex = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_chr_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  regex = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_character_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  regex = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

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

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

to_chr_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_character_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Details

These functions have two important differences from base::as.character():

• lists and data.frames are not coerced to character. In base R, such objects are coerced to character representations of their elements. For example, as.character(list(1:3)) returns "1:10". In the unlikely event that this is the expected behavior, use as.character() instead.

• NULL values can be rejected as part of the call to this function (with allow_null = FALSE).

Named functions are converted to their string name. If the function comes from a package namespace, the result is a "pkg::fn" string. For example, to_chr(mean) returns "base::mean". Anonymous functions produce an error.

To preserve the original call-site symbol when to_chr() is called inside a wrapper function, use the embrace operator {{ }}. For example:

my_wrapper <- function(fn) {
  to_chr({{ fn }})
}
my_wrapper(mean)  # Returns "base::mean"

Value

The argument as a character vector.

See Also

Other character functions: are_chr_ish(), specify_chr(), to()

Other stabilization functions: stabilize_arg(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_lst(), stabilize_present()

Examples

to_chr("a")
to_chr(letters)
to_chr(1:10)
to_chr(1 + 0i)
to_chr(NULL)
try(to_chr(NULL, allow_null = FALSE))

# Named functions are converted to their string name.
to_chr(mean)
to_chr(base::mean)
try(to_chr(function(x) x))

to_chr_scalar("a")
try(to_chr_scalar(letters))

stabilize_chr(letters)
stabilize_chr(1:10)
stabilize_chr(NULL)
try(stabilize_chr(NULL, allow_null = FALSE))
try(stabilize_chr(c("a", NA), allow_na = FALSE))
try(stabilize_chr(letters, min_size = 50))
try(stabilize_chr(letters, max_size = 20))
try(stabilize_chr(c("hide", "find", "find", "hide"), regex = "hide"))

stabilize_chr_scalar(TRUE)
stabilize_chr_scalar("TRUE")
try(stabilize_chr_scalar(c(TRUE, FALSE, TRUE)))
try(stabilize_chr_scalar(NULL))
stabilize_chr_scalar(NULL, allow_null = TRUE)

Ensure a double argument meets expectations

Description

to_dbl() checks whether an argument can be coerced to double without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_double is a synonym of to_dbl().

stabilize_dbl() can check more details about the argument, but is slower than to_dbl(). stabilise_dbl(), stabilize_double(), and stabilise_double() are synonyms of stabilize_dbl().

stabilize_dbl_scalar() and to_dbl_scalar() are optimized to check for length-1 double vectors. stabilise_dbl_scalar, stabilize_double_scalar(), and stabilise_double_scalar are synonyms of stabilize_dbl_scalar(), and to_double_scalar() is a synonym of to_dbl_scalar().

Usage

stabilize_dbl(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_double(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_dbl(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_double(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_dbl_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_double_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_dbl_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_double_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

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

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

## S3 method for class ''NULL''
to_dbl(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

## S3 method for class 'character'
to_dbl(
  x,
  ...,
  coerce_character = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'factor'
to_dbl(
  x,
  ...,
  coerce_factor = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_dbl_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_double_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as a double vector.

See Also

Other double functions: are_dbl_ish(), specify_dbl(), to()

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_lst(), stabilize_present()

Examples

to_dbl(1:10)
to_dbl("1.1")
to_dbl(1 + 0i)
to_dbl(NULL)
try(to_dbl("a"))
try(to_dbl("1.1", coerce_character = FALSE))

to_dbl_scalar("1.1")
try(to_dbl_scalar(1:10))

stabilize_dbl(1:10)
stabilize_dbl("1.1")
stabilize_dbl(1 + 0i)
stabilize_dbl(NULL)
try(stabilize_dbl(NULL, allow_null = FALSE))
try(stabilize_dbl(c(1.1, NA), allow_na = FALSE))
try(stabilize_dbl(letters))
try(stabilize_dbl("1.1", coerce_character = FALSE))
try(stabilize_dbl(factor(c("1.1", "a"))))
try(stabilize_dbl(factor("1.1"), coerce_factor = FALSE))
try(stabilize_dbl(1:10, min_value = 3.5))
try(stabilize_dbl(1:10, max_value = 7.5))

stabilize_dbl_scalar(1.0)
stabilize_dbl_scalar("1.1")
try(stabilize_dbl_scalar(1:10))
try(stabilize_dbl_scalar(NULL))
stabilize_dbl_scalar(NULL, allow_null = TRUE)

Ensure a data frame argument meets expectations

Description

stabilize_df() validates the structure and contents of a data frame. It can check that specific named columns are present and valid, that extra columns conform to a shared rule, that required column names are present, and that the row count is within specified bounds. stabilise_df(), stabilize_data_frame(), and stabilise_data_frame() are synonyms of stabilize_df().

Usage

stabilize_df(
  .x,
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_df(
  .x,
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilize_data_frame(
  .x,
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_data_frame(
  .x,
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

Arguments

Value

The validated data frame.

See Also

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

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_lst(), stabilize_present()

Examples

# Basic validation: required columns with type specs
stabilize_df(
  data.frame(name = "Alice", age = 30L),
  name = specify_chr_scalar(),
  age = specify_int_scalar()
)

# Allow extra columns with .extra_cols
stabilize_df(
  data.frame(name = "Alice", age = 30L, score = 99.5),
  name = specify_chr_scalar(),
  age = specify_int_scalar(),
  .extra_cols = stabilize_present
)

# Check required column names without validating contents
stabilize_df(
  mtcars,
  .col_names = c("mpg", "cyl"),
  .extra_cols = stabilize_present
)

# Enforce row count constraints
try(
  stabilize_df(mtcars[0, ], .min_rows = 1, .extra_cols = stabilize_present)
)

# NULL is allowed by default
stabilize_df(NULL)
try(stabilize_df(NULL, .allow_null = FALSE))

# Coercible inputs such as named lists are accepted
stabilize_df(
  list(name = "Alice", age = 30L),
  name = specify_chr_scalar(),
  age = specify_int_scalar()
)

# Non-coercible inputs are rejected
try(stabilize_df("not a data frame"))

Ensure a factor argument meets expectations

Description

to_fct() checks whether an argument can be coerced to a factor without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_factor is a synonym of to_fct().

stabilize_fct() can check more details about the argument, but is slower than to_fct(). stabilise_fct(), stabilize_factor(), and stabilise_factor() are synonyms of stabilize_fct().

stabilize_fct_scalar() and to_fct_scalar() are optimized to check for length-1 factors. stabilise_fct_scalar, stabilize_factor_scalar(), and stabilise_factor_scalar are synonyms of stabilize_fct_scalar(), and to_factor_scalar() is a synonym of to_fct_scalar().

Usage

stabilize_fct(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_factor(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_fct(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_factor(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_fct_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_factor_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_fct_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_factor_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_fct(
  x,
  ...,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_factor(
  x,
  ...,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class ''NULL''
to_fct(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

to_fct_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_factor_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  levels = NULL,
  to_na = character(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Details

These functions have important differences from base::as.factor() and base::factor():

• Values are never silently coerced to NA unless they are explicitly supplied in the to_na argument.

• NULL values can be rejected as part of the call to this function (with allow_null = FALSE).

Value

The argument as a factor.

See Also

Other factor functions: are_fct_ish(), specify_fct(), to()

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_int(), stabilize_lgl(), stabilize_lst(), stabilize_present()

Examples

to_fct("a")
to_fct(1:10)
to_fct(NULL)
try(to_fct(letters[1:5], levels = c("a", "c"), to_na = "b"))

to_fct_scalar("a")
try(to_fct_scalar(letters))

stabilize_fct(letters)
try(stabilize_fct(NULL, allow_null = FALSE))
try(stabilize_fct(c("a", NA), allow_na = FALSE))
try(stabilize_fct(c("a", "b", "c"), min_size = 5))
try(stabilize_fct(c("a", "b", "c"), max_size = 2))

stabilize_fct_scalar("a")
try(stabilize_fct_scalar(letters))
try(stabilize_fct_scalar("c", levels = c("a", "b")))

Ensure an integer argument meets expectations

Description

to_int() checks whether an argument can be coerced to integer without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_integer is a synonym of to_int().

stabilize_int() can check more details about the argument, but is slower than to_int(). stabilise_int(), stabilize_integer(), and stabilise_integer() are synonyms of stabilize_int().

stabilize_int_scalar() and to_int_scalar() are optimized to check for length-1 integer vectors. stabilise_int_scalar, stabilize_integer_scalar(), and stabilise_integer_scalar are synonyms of stabilize_int_scalar(), and to_integer_scalar() is a synonym of to_int_scalar().

Usage

stabilize_int(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_integer(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_int(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_integer(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_int_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_integer_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_int_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_integer_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

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

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

## S3 method for class ''NULL''
to_int(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

## S3 method for class 'character'
to_int(
  x,
  ...,
  coerce_character = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'factor'
to_int(
  x,
  ...,
  coerce_factor = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_int_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_integer_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as an integer vector.

See Also

Other integer functions: are_int_ish(), specify_int(), to()

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_lgl(), stabilize_lst(), stabilize_present()

Examples

to_int(1:10)
to_int("1")
to_int(1 + 0i)
to_int(NULL)
try(to_int(c(1, 2, 3.1, 4, 5.2)))
try(to_int("1", coerce_character = FALSE))
try(to_int(c("1", "2", "3.1", "4", "5.2")))

to_int_scalar("1")
try(to_int_scalar(1:10))

stabilize_int(1:10)
stabilize_int("1")
stabilize_int(1 + 0i)
stabilize_int(NULL)
try(stabilize_int(NULL, allow_null = FALSE))
try(stabilize_int(c(1, NA), allow_na = FALSE))
try(stabilize_int(letters))
try(stabilize_int("1", coerce_character = FALSE))
try(stabilize_int(factor(c("1", "a"))))
try(stabilize_int(factor("1"), coerce_factor = FALSE))
try(stabilize_int(1:10, min_value = 3))
try(stabilize_int(1:10, max_value = 7))

stabilize_int_scalar(1L)
stabilize_int_scalar("1")
try(stabilize_int_scalar(1:10))
try(stabilize_int_scalar(NULL))
stabilize_int_scalar(NULL, allow_null = TRUE)

Ensure a logical argument meets expectations

Description

to_lgl() checks whether an argument can be coerced to logical without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_logical is a synonym of to_lgl().

stabilize_lgl() can check more details about the argument, but is slower than to_lgl(). stabilise_lgl(), stabilize_logical(), and stabilise_logical() are synonyms of stabilize_lgl().

stabilize_lgl_scalar() and to_lgl_scalar() are optimized to check for length-1 logical vectors. stabilise_lgl_scalar(), stabilize_logical_scalar(), and stabilise_logical_scalar() are synonyms of stabilize_lgl_scalar(), and to_logical_scalar() is a synonym of to_lgl_scalar().

Usage

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

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

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

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

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

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

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

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

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

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

## S3 method for class ''NULL''
to_lgl(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

to_lgl_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_logical_scalar(
  x,
  ...,
  allow_null = FALSE,
  allow_zero_length = FALSE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as a logical vector.

See Also

Other logical functions: are_lgl_ish(), specify_lgl(), to()

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lst(), stabilize_present()

Examples

to_lgl(TRUE)
to_lgl("TRUE")
to_lgl(1:10)
to_lgl(NULL)
try(to_lgl(NULL, allow_null = FALSE))
try(to_lgl(letters))
try(to_lgl(list(TRUE)))

to_lgl_scalar("TRUE")
try(to_lgl_scalar(c(TRUE, FALSE)))

stabilize_lgl(c(TRUE, FALSE, TRUE))
stabilize_lgl("true")
stabilize_lgl(NULL)
try(stabilize_lgl(NULL, allow_null = FALSE))
try(stabilize_lgl(c(TRUE, NA), allow_na = FALSE))
try(stabilize_lgl(letters))
try(stabilize_lgl(c(TRUE, FALSE, TRUE), min_size = 5))
try(stabilize_lgl(c(TRUE, FALSE, TRUE), max_size = 2))

stabilize_lgl_scalar(TRUE)
stabilize_lgl_scalar("TRUE")
try(stabilize_lgl_scalar(c(TRUE, FALSE, TRUE)))
try(stabilize_lgl_scalar(NULL))
stabilize_lgl_scalar(NULL, allow_null = TRUE)

Ensure a list argument meets expectations

Description

stabilize_lst() validates the structure and contents of a list. It can check that specific named elements are present and valid, that extra named elements conform to a shared rule, and that unnamed elements conform to a shared rule. stabilise_lst(), stabilize_list(), and stabilise_list() are synonyms of stabilize_lst().

Usage

stabilize_lst(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilize_list(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_lst(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_list(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

Arguments

Value

The validated list.

See Also

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

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_present()

Examples

# Basic validation: named required elements
stabilize_lst(
  list(name = "Alice", age = 30L),
  name = specify_chr_scalar(),
  age = specify_int_scalar()
)

# Allow any non-NULL element with stabilize_present
stabilize_lst(list(data = mtcars), data = stabilize_present)

# Allow extra named elements via .named
stabilize_lst(
  list(a = 1L, b = 2L, c = 3L),
  .named = specify_int_scalar()
)

# Allow unnamed elements via .unnamed
stabilize_lst(list(1L, 2L, 3L), .unnamed = specify_int_scalar())

# NULL is allowed by default
stabilize_lst(NULL)
try(stabilize_lst(NULL, .allow_null = FALSE))

# Enforce size constraints
try(stabilize_lst(list(a = 1L), .min_size = 2))

# Reject duplicate names by default; opt in to allow them
try(stabilize_lst(list(a = 1L, a = 2L), .named = specify_int_scalar()))
stabilize_lst(
  list(a = 1L, a = 2L),
  .named = specify_int_scalar(),
  .allow_duplicate_names = TRUE
)

Require a value to be non-NULL

Description

stabilize_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

stabilize_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: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_lst()

Examples

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

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

Convert a value to a target type

Description

to() coerces x to the type of .to, dispatching on the class of .to to the appropriate ⁠to_*()⁠ function.

Usage

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

## S3 method for class 'character'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'double'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'data.frame'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'factor'
to(
  x,
  .to,
  ...,
  levels = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class ''function''
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'integer'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'logical'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class 'list'
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## S3 method for class ''NULL''
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## Default S3 method:
to(
  x,
  .to,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

x coerced to the type of .to.

See Also

Other character functions: are_chr_ish(), specify_chr(), stabilize_chr()

Other double functions: are_dbl_ish(), specify_dbl(), stabilize_dbl()

Other integer functions: are_int_ish(), specify_int(), stabilize_int()

Other logical functions: are_lgl_ish(), specify_lgl(), stabilize_lgl()

Other factor functions: are_fct_ish(), specify_fct(), stabilize_fct()

Other function functions: are_fn_ish(), to_fn()

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

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

Examples

to(1L, double())
to(1.0, integer())
to(TRUE, character())
to("1", integer())
to(c("a", "b"), factor(levels = c("a", "b", "c")))
to("mean", mean)

Ensure a data frame argument meets expectations

Description

to_df() checks whether an argument can be coerced to a data frame, returning it silently if so. Otherwise an informative error message is signaled. to_data_frame() is a synonym of to_df().

Usage

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

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

## S3 method for class ''NULL''
to_df(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

Arguments

Value

The argument as a data frame.

See Also

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

Examples

to_df(mtcars)
to_df(list(name = "Alice", age = 30L))
to_df(NULL)
try(to_df(NULL, allow_null = FALSE))
try(to_df(c("a", "b", "c")))
to_df(letters)

Coerce to a function

Description

to_fn() coerces x to a function. to_function() is a synonym of to_fn().

Usage

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

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

## S3 method for class ''NULL''
to_fn(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

## S3 method for class 'character'
to_fn(
  x,
  ...,
  allow_null = TRUE,
  definition_env = rlang::global_env(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

## Default S3 method:
to_fn(
  x,
  ...,
  definition_env = rlang::global_env(),
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Details

Unlike rlang::as_function(), to_fn() supports namespaced function names such as "pkg::fn" in the character method. When the input is a length-0 character vector, to_fn() returns NULL (subject to allow_null). An input of length > 1 is always an error.

Value

A function.

See Also

Other function functions: are_fn_ish(), to()

Examples

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

Ensure a list argument meets expectations

Description

to_lst() checks whether an argument can be coerced to a list without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_list() is a synonym of to_lst().

Usage

to_lst(x, ..., x_arg = caller_arg(x), call = caller_env())

to_list(x, ..., x_arg = caller_arg(x), call = caller_env())

## S3 method for class 'list'
to_lst(x, ..., x_arg = caller_arg(x), call = caller_env())

## Default S3 method:
to_lst(x, ..., x_arg = caller_arg(x), call = caller_env())

## S3 method for class ''NULL''
to_lst(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())

## S3 method for class ''function''
to_lst(
  x,
  ...,
  coerce_function = FALSE,
  x_arg = caller_arg(x),
  call = caller_env()
)

Arguments

Details

This function has important distinctions from base::as.list():

• Functions can be rejected as part of the call to this function (with coerce_function = FALSE, the default). If they are allowed, they'll be coerced to a list concatenating their formals and body (as with base::as.list().

• Primitive functions (such as base::is.na() or base::is.list()) always throw an error, rather than returning list(NULL).

• NULL values can be rejected as part of the call to this function (with allow_null = FALSE).

Value

The argument as a list.

See Also

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