Title:	Stabilize Function Arguments
Version:	0.2.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.api2r.org/, https://github.com/api2r/stbl
BugReports:	https://github.com/api2r/stbl/issues
Depends:	R (≥ 4.1)
Imports:	cli, glue, rlang (≥ 1.1.0), vctrs
Suggests:	knitr, rmarkdown, stringi, stringr, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-09-16 20:42:56 UTC; jonth
Author:	Jon Harmon [aut, cre, cph]
Maintainer:	Jon Harmon <jonthegeek@gmail.com>
Repository:	CRAN
Date/Publication:	2025-09-16 21:00: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]

See Also

Useful links:

• https://stbl.api2r.org/

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

• Report bugs at https://github.com/api2r/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 character to double coercion failures

Description

Check for character to double coercion failures

Usage

.are_not_dbl_ish_chr(x)

Arguments

Value

A logical vector where TRUE indicates a failure.

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.

Check for character to integer coercion failures

Description

Check for character to integer coercion failures

Usage

.are_not_int_ish_chr(x)

Arguments

Value

A logical matrix with two columns: non_number and bad_precision.

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

Check for character to integer coercion failures

Description

Check for character to integer coercion failures

Usage

.check_chr_to_int_failures(x, x_class, x_arg, call)

Arguments

Value

NULL, invisibly, if x passes all checks.

Check for NA values

Description

Checks for NA values in x, throwing an error if any are found and allow_na is FALSE.

Usage

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

Arguments

Value

NULL, invisibly, if x passes the check.

Check if an object is a scalar

Description

Checks if an object is a scalar, allowing for NULL and zero-length vectors if specified.

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, if x passes the check.

Check the size of an object

Description

Checks if the size of x (from vctrs::vec_size()) is within the bounds of min_size and max_size.

Usage

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

Arguments

Value

NULL, invisibly, if x passes the check.

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, if x is not greater than y.

Escape curly braces for safe printing with cli

Description

Replaces single curly braces (⁠{⁠, ⁠}⁠) with double curly braces (⁠{{⁠, ⁠}}⁠) so that they are interpreted as literal characters by cli::cli_abort() and not as expressions to be evaluated.

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

A wrapper around level-coercion helpers.

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

Checks for values in x that are not present in levels and throws an error if any are found.

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

A helper that converts specified values in x to NA.

Usage

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

Arguments

Value

x with specified values converted to NA.

Compile an error class

Description

Compile an error class

Usage

.compile_error_class(...)

Arguments

Value

A length-1 character vector.

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

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

Always return FALSE

Description

A helper to force the slow path in .to_cls_scalar() for factors, since rlang::is_scalar_factor() does not exist.

Usage

.fast_false(x)

Arguments

Value

FALSE, always.

Safely find failure locations in a vector

Description

Run check_fn(x, check_value) if check_value isn't NULL.

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 custom delimiters

Description

This wrapper sets the .open and .close arguments of glue::glue() to [ and ⁠]⁠, respectively. This allows for safe use of glue interpolation within messages that will be processed by cli::cli_abort(), which uses ⁠{⁠ and ⁠}⁠ for its own styling.

Usage

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

Arguments

Value

A character string with evaluated expressions.

Detect a regex pattern in a character vector

Description

A wrapper around stringi::stri_detect_regex() and base::grepl() that prefers the stringi implementation if the package is available.

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.

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

Stabilize an object of a specific class

Description

A helper used by the ⁠stabilize_*()⁠ functions to provide a standard set of checks.

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

A helper used by the ⁠stabilize_*_scalar()⁠ functions to provide a standard set of checks.

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 = TRUE,
  allow_zero_length = TRUE,
  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

A wrapper around cli::cli_abort() to throw classed errors.

Usage

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

Arguments

Stop for bad factor levels

Description

Throws a standardized error when values are not found in the provided factor levels.

Usage

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

Arguments

Value

This function is called for its side effect of throwing an error and does not return a value.

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

This function is called for its side effect of throwing an error and does not return a value.

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

This function is called for its side effect of throwing an error and does not return a value.

Abort with a standardized "must" message

Description

Abort with a standardized "must" message

Usage

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

Arguments

Value

This function is called for its side effect of throwing an error and does not return a value.

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

This function is called for its side effect of throwing an error and does not return a value.

Coerce an object from a factor to a specific class

Description

A helper that wraps around a ⁠to_*()⁠ function to provide a standard way to coerce factors.

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 a list to a specific class

Description

Coerce a list to a specific class

Usage

.to_cls_from_list(
  x,
  to_cls_fn,
  to_class,
  ...,
  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

A helper that wraps around a ⁠to_*_scalar()⁠ function to provide a standard set of checks.

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.

Ensure an argument is NULL

Description

If allow_null is TRUE, coerce x to NULL. Otherwise throw an informative error.

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

A helper that wraps around a ⁠to_*()⁠ function to provide a standard way to coerce complex numbers.

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.

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.

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

Usage

are_chr_ish(x, ...)

is_chr_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.

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.

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

Usage

are_dbl_ish(x, ...)

is_dbl_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.

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.

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

Usage

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

is_fct_ish(x, ...)

## 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.

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

# 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 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.

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

Usage

are_int_ish(x, ...)

is_int_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.

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.

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

Usage

are_lgl_ish(x, ...)

is_lgl_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.

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

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

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

Arguments

Value

The regex value with names() equal to the generated error message.

Examples

regex_must_match("[aeiou]")

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

Create a 'must not match' regex rule

Description

Attach a standardized error message to a regex argument that specifies that the pattern must not be matched. This is a wrapper around regex_must_match() that sets the negate attribute to TRUE.

Usage

regex_must_not_match(regex)

Arguments

Value

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

Examples

regex_must_not_match("[aeiou]")

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.

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.

stabilize_chr() can check more details about the argument, but is slower than to_chr().

stabilize_chr_scalar() and to_chr_scalar() are optimized to check for length-1 character vectors.

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_chr_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  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)
)

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

to_chr_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  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).

Value

The argument as a character vector.

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

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)))
stabilize_chr_scalar(NULL)
try(stabilize_chr_scalar(NULL, allow_null = FALSE))

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.

stabilize_dbl() can check more details about the argument, but is slower than to_dbl().

stabilize_dbl_scalar() and to_dbl_scalar() are optimized to check for length-1 double vectors.

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_dbl_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  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)
)

## 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 = TRUE,
  allow_zero_length = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as a double.

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))
stabilize_dbl_scalar(NULL)
try(stabilize_dbl_scalar(NULL, allow_null = FALSE))

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.

stabilize_fct() can check more details about the argument, but is slower than to_fct().

stabilize_fct_scalar() and to_fct_scalar() are optimized to check for length-1 factors.

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_fct_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  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)
)

## 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 = TRUE,
  allow_zero_length = TRUE,
  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.

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.

stabilize_int() can check more details about the argument, but is slower than to_int().

stabilize_int_scalar() and to_int_scalar() are optimized to check for length-1 integer vectors.

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_int_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  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)
)

## 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 = TRUE,
  allow_zero_length = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as an integer.

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))
stabilize_int_scalar(NULL)
try(stabilize_int_scalar(NULL, allow_null = FALSE))

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.

stabilize_lgl() can check more details about the argument, but is slower than to_lgl().

stabilize_lgl_scalar() and to_lgl_scalar() are optimized to check for length-1 logical vectors.

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

to_lgl(
  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 = TRUE,
  allow_zero_length = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

Value

The argument as a logical vector.

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)))
stabilize_lgl_scalar(NULL)
try(stabilize_lgl_scalar(NULL, allow_null = FALSE))