| Title: | Stabilize Objects |
| Version: | 0.5.0 |
| Description: | A set of consistent, opinionated functions to quickly check objects, 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, methods, rlang (≥ 1.0.3), vctrs |
| Suggests: | covr, hms, knitr, lubridate, rmarkdown, stringi, stringr, testthat (≥ 3.3.0) |
| VignetteBuilder: | knitr |
| Config/Needs/website: | quarto |
| Config/roxygen2/version: | 8.1.0 |
| Config/testthat/edition: | 3 |
| Config/testthat/parallel: | true |
| Encoding: | UTF-8 |
| Language: | en-US |
| NeedsCompilation: | yes |
| Packaged: | 2026-09-13 15:54:44 UTC; jonth |
| Author: | Jon Harmon  [aut,
cre, cph] |
| Maintainer: | Jon Harmon <jonthegeek@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-09-13 16:20:02 UTC |
stbl: Stabilize Objects
Description
A set of consistent, opinionated functions to quickly check objects, 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:
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
x |
The object to check for |
y |
The value to return if |
Value
NULL or the value of y.
Apply every function to x independently, requiring identical results
Description
Applies each function in fns to the original x, independently. Errors
if any function fails, or if the successful results disagree.
Usage
.apply_fns_requiring_consensus(x, fns, x_arg, call)
Arguments
x |
The value to test. |
fns |
|
x_arg |
( |
call |
|
Value
The common result of applying every function in fns to x.
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
rule |
( |
x |
The object to stabilize. |
x_arg |
( |
call |
|
Value
A list with a message character vector and integer locations of
the failing elements if the rule fails, otherwise NULL.
Apply a single spec to x, stopping if it errors
Description
Apply a single spec to x, stopping if it errors
Usage
.apply_spec_or_stop(fn, x, x_arg, call)
Arguments
fn |
A stabilizer or coercion function to apply to |
x |
The value to test. |
x_arg |
( |
call |
|
Value
The result of applying fn to x.
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
x |
The object to check. |
levels |
|
to_na |
|
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
spec_fn |
A stabilizer function. |
.x |
The value to validate. |
.x_arg |
( |
.call |
|
Value
The validated value.
Capture the non-missing arguments of the calling function
Description
Used inside specify_*() functions to build the factory_args list passed
to .specify_cls(), keeping only the arguments that the caller of the
specify_*() function actually supplied (as opposed to those left at
their default value).
Usage
.capture_factory_args()
Value
A named list of the values of arguments that weren't left missing
in the function that called .capture_factory_args().
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
obj_expr |
An unevaluated expression (from |
condition_name |
( |
muffle_restart |
( |
env |
( |
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
x |
The object to stabilize. |
x_arg |
( |
call |
|
Value
NULL invisibly (called for side effects).
Check that all elements are members of an allowed set of values
Description
Check that all elements are members of an allowed set of values
Usage
.check_allowed_values(
x,
allowed_values,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to check. |
allowed_values |
A vector of permitted values, already coerced to the
same type as |
x_arg |
( |
call |
|
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(x, failures, x_class, to, due_to, x_arg, call)
Arguments
x |
The object to stabilize. |
failures |
|
x_class |
( |
to |
The target object for the coercion. |
due_to |
( |
x_arg |
( |
call |
|
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(x, res, x_class, x_arg, call)
Arguments
x |
The object to stabilize. |
res |
A list returned by |
x_class |
( |
x_arg |
( |
call |
|
Value
NULL invisibly (called for side effects).
Apply a spec and check that it agrees with the running result
Description
Apply a spec and check that it agrees with the running result
Usage
.check_consensus(result, fn, x, x_arg, call)
Arguments
result |
The value obtained from the specs applied so far. |
fn |
A stabilizer or coercion function to apply to |
x |
The value to test. |
x_arg |
( |
call |
|
Value
fn's result, if it agrees with result; otherwise, throws an
error.
Check for complex to integer coercion failures
Description
Check for complex to integer coercion failures
Usage
.check_cpx_to_int_failures(x, res, x_class, x_arg, call)
Arguments
x |
The object to stabilize. |
res |
A list returned by |
x_class |
( |
x_arg |
( |
call |
|
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(x, res, x_class, x_arg, call)
Arguments
x |
The object to stabilize. |
res |
A list returned by |
x_class |
( |
x_arg |
( |
call |
|
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
.x |
|
col_names |
|
x_arg |
( |
call |
|
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
.x |
|
min_rows |
( |
max_rows |
( |
x_arg |
( |
call |
|
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
.x |
The object to stabilize. |
.allow_duplicate_names |
( |
.x_arg |
( |
.call |
|
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
x |
The object to check. |
coerce_function |
( |
x_arg |
( |
call |
|
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
x |
The object to check. |
x_arg |
( |
call |
|
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(x, valid, to, x_class, x_arg, call)
Arguments
x |
The object to stabilize. |
valid |
|
to |
The target object for the coercion. |
x_class |
( |
x_arg |
( |
call |
|
Value
NULL invisibly (called for side effects).
Signal an error when the match count falls outside min_matches/max_matches
Description
Signal an error when the match count falls outside min_matches/max_matches
Usage
.check_match_count(
matched_locations,
min_matches,
max_matches,
x_arg,
x_class,
call
)
Arguments
matched_locations |
|
x_arg |
( |
x_class |
( |
call |
|
Value
NULL, invisibly, if the match count is within bounds.
Check that all elements are integer multiples of a value
Description
Doubles are compared with a small relative tolerance
(sqrt(.Machine$double.eps), the same default used by
base::all.equal()) so that representable rounding error (e.g.
0.3 / 0.1) doesn't produce spurious failures.
Usage
.check_multiple_of(x, multiple_of, x_arg = caller_arg(x), call = caller_env())
Arguments
x |
The object to check. |
multiple_of |
( |
x_arg |
( |
call |
|
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
x |
The object to check. |
allow_na |
( |
x_arg |
( |
call |
|
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
x |
The object to stabilize. |
x_arg |
( |
call |
|
x_class |
( |
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
x |
The object to check. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
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
x |
The object to check. |
min_size |
( |
max_size |
( |
x_arg |
( |
call |
|
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
... |
Named stabilizer functions, such as |
.call |
|
Value
NULL, invisibly, if all elements are named.
Check that a specs list is non-empty
Description
Check that a specs list is non-empty
Usage
.check_specs_not_empty(fns, .call = caller_env())
Arguments
fns |
|
.call |
|
Value
NULL, invisibly, if the list is non-empty.
Check that all specs passed via ... are unnamed
Description
Check that all specs passed via ... are unnamed
Usage
.check_specs_unnamed(fns, .call = caller_env())
Arguments
fns |
|
.call |
|
Value
NULL, invisibly, if all elements are unnamed.
Check that a time zone is valid
Description
Check that a time zone is valid
Usage
.check_tz(tz, x_arg = "tz", call = caller_env())
Arguments
tz |
( |
x_arg |
( |
call |
|
Value
tz, coerced to a scalar character, if it is valid.
Check that all elements are unique
Description
Check that all elements are unique
Usage
.check_unique(x, unique = FALSE, x_arg = caller_arg(x), call = caller_env())
Arguments
x |
The object to check. |
unique |
( |
x_arg |
( |
call |
|
Value
NULL invisibly (called for side effects).
Check character values against character count and regex patterns
Description
Check character values against character count and regex patterns
Usage
.check_value_chr(
x,
regex,
min_characters = NULL,
max_characters = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
regex |
|
min_characters |
( |
max_characters |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check date values against min, max, and allowed values
Description
Check date values against min, max, and allowed values
Usage
.check_value_date(
x,
min_value,
max_value,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check date-time values against min, max, and allowed values
Description
Base R has no C-level range routines for base::POSIXct as it does for
double, so the comparisons are performed in plain R. min_value,
max_value, and allowed_values are coerced to base::POSIXct first so
that character or numeric bounds are accepted.
Usage
.check_value_dttm(
x,
min_value,
max_value,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check duration values against min, max, and allowed values
Description
min_value, max_value, and allowed_values are coerced to
lubridate::Period first so that character or numeric bounds are
accepted.
Usage
.check_value_dur(
x,
min_value,
max_value,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check logical values against allowed values
Description
Check logical values against allowed values
Usage
.check_value_lgl(
x,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check character values against character count constraints
Description
Check character values against character count constraints
Usage
.check_value_n_characters(
x,
min_characters = NULL,
max_characters = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_characters |
( |
max_characters |
( |
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check character values against regex patterns
Description
Check character values against regex patterns
Usage
.check_value_regex(x, regex, x_arg = caller_arg(x), call = caller_env())
Arguments
x |
The object to stabilize. |
regex |
|
x_arg |
( |
call |
|
Value
NULL, invisibly, if x passes all checks.
Check time-of-day values against min, max, and allowed values
Description
min_value, max_value, and allowed_values are coerced to hms::hms()
first so that character or numeric bounds are accepted.
Usage
.check_value_time(
x,
min_value,
max_value,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
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
x |
The object to check. |
y |
The value to compare against. |
x_arg |
( |
y_arg |
( |
call |
|
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)
.check_min_dbl_exclusive(x, min_val)
.check_max_dbl_exclusive(x, max_val)
Arguments
x |
The object to stabilize. |
levels |
|
to_na |
|
to |
The target object for the coercion. |
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(), .check_max_dbl(),
.check_min_dbl_exclusive(), and .check_max_dbl_exclusive(): 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
x |
A quosure wrapping the function. |
x_name |
The name used to refer to the function at the call site. |
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
x_expr |
A |
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
msg |
|
Value
The messages with curly braces escaped.
Wrap text in cli markup
Description
Wrap text in cli markup
Usage
.cli_mark(x, tag)
Arguments
x |
|
tag |
|
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
x |
The object to stabilize. |
levels |
|
to_na |
|
x_arg |
( |
call |
|
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
x |
The object to stabilize. |
levels |
|
to_na |
|
x_arg |
( |
call |
|
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
x |
The object to stabilize. |
to_na |
|
call |
|
Value
x with specified values converted to NA.
Paste together collapsing with -
Description
Paste together collapsing with -
Usage
.collapse_dash(...)
Arguments
... |
Things to paste. |
Value
A length-1 character vector, or NULL if ... is empty.
Paste together with - separator
Description
Paste together with - separator
Usage
.compile_dash(...)
Arguments
... |
Things to paste. |
Value
A length-1 character vector, or NULL if ... is empty.
Compile a condition class chain
Description
Compile a condition class chain
Usage
.compile_pkg_condition_classes(package, ...)
Arguments
package |
( |
... |
|
Value
A character vector.
Compile an error class chain
Description
Compile an error class chain
Usage
.compile_pkg_error_classes(package, ...)
Arguments
package |
( |
... |
|
Value
A character vector of classes.
Compile a message class chain
Description
Compile a message class chain
Usage
.compile_pkg_message_classes(package, ...)
Arguments
package |
( |
... |
|
Value
A character vector of classes.
Compile a warning class chain
Description
Compile a warning class chain
Usage
.compile_pkg_warning_classes(package, ...)
Arguments
package |
( |
... |
|
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
check_dupes |
|
stabilizer |
( |
factory_args |
Arguments passed to |
... |
Not used. Included to avoid confusion in R CMD check. |
call |
|
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
stabilizer |
( |
scalar |
( |
Value
The symbol of the stabilizer function to call.
An empty date object for error messages
Description
object_type() renders a base::Date as "Date", but the date family uses
the lowercase "date" in its coercion classes and messages. This returns an
empty object that renders as "date" so error subclasses read
<stbl-error-incompatible_values-date>.
Usage
.date_type_obj()
Value
A zero-length object whose object_type() is "date".
Expand a date format into date and date-time variants
Description
Expand a date format into date and date-time variants
Usage
.datetime_format_variants(date_format)
Arguments
date_format |
( |
Value
A character() vector: date_format with a "T%H:%M:%S" suffix
(only when date_format is "%Y-%m-%d"), with a " %H:%M:%S" suffix,
and bare, in that order.
An empty date-time object for error messages
Description
object_type() renders a base::POSIXct as "POSIXct", but the datetime
family uses "datetime" in its coercion classes and messages, to match the
to_dttm()/stabilize_dttm() function names. This returns an empty
object that renders as "datetime" so error subclasses read
<stbl-error-incompatible_values-datetime>.
Usage
.datetime_type_obj()
Value
A zero-length object whose object_type() is "datetime".
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
x_arg |
( |
msg |
|
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
x |
The object to stabilize. |
success |
|
negate |
( |
Value
A named character vector to be used as additional_msg in
.stop_must().
Describe a date value validation failure
Description
Describe a date value validation failure
Usage
.describe_failure_date_value(x, failures, direction, target_value, x_arg)
Arguments
x |
|
failures |
|
direction |
|
target_value |
|
x_arg |
( |
Value
A named character vector for .stbl_abort(), or NULL.
Describe a numeric value validation failure
Description
Describe a numeric value validation failure
Usage
.describe_failure_dbl_value(
x,
failure_locations,
direction,
target_value,
exclusive = FALSE,
x_arg
)
Arguments
x |
|
failure_locations |
|
direction |
|
target_value |
|
exclusive |
|
x_arg |
( |
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
x |
|
msg_main |
|
direction |
|
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
x |
|
msg_main |
|
direction |
|
Value
A named character vector.
Describe a date-time value validation failure
Description
Describe a date-time value validation failure
Usage
.describe_failure_dttm_value(x, failures, direction, target_value, x_arg)
Arguments
x |
|
failures |
|
direction |
|
target_value |
|
x_arg |
( |
Value
A named character vector for .stbl_abort(), or NULL.
Describe a duration value validation failure
Description
Describe a duration value validation failure
Usage
.describe_failure_dur_value(x, failures, direction, target_value, x_arg)
Arguments
x |
|
failures |
|
direction |
|
target_value |
|
x_arg |
( |
Value
A named character vector for .stbl_abort(), or NULL.
Describe a character count validation failure
Description
Describe a character count validation failure
Usage
.describe_failure_n_characters(x, failure_locations, target, direction, x_arg)
Arguments
x |
|
failure_locations |
|
target |
( |
direction |
( |
x_arg |
( |
Value
A named character vector for .stbl_abort().
Describe a time-of-day value validation failure
Description
Describe a time-of-day value validation failure
Usage
.describe_failure_time_value(x, failures, direction, target_value, x_arg)
Arguments
x |
|
failures |
|
direction |
|
target_value |
|
x_arg |
( |
Value
A named character vector for .stbl_abort(), or NULL.
An empty duration object for error messages
Description
object_type() renders a lubridate::Period as "Period", but the
duration family uses "duration" in its coercion classes and messages, to
match the to_dur()/stabilize_dur() function names. This
returns an empty object that renders as "duration" so error subclasses
read <stbl-error-incompatible_values-duration>.
Usage
.duration_type_obj()
Value
A zero-length object whose object_type() is "duration".
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
x |
The object to check. |
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,
error,
transform,
variant,
env
)
Arguments
obj_expr |
An unevaluated expression (from |
package |
( |
class_components |
( |
expect_fn_name |
( |
expect_fn |
( |
check_installed_msg |
( |
error |
( |
transform |
( |
variant |
( |
env |
( |
Value
The result of testthat::expect_snapshot(), invisibly.
Extract a summary line from a stabilizer error condition
Description
Returns the first line of the condition message. If the condition carries a
"Locations:" bullet in its body (as set by .stop_incompatible()), that
text is appended in parentheses so callers can see which elements failed.
Usage
.extract_stabilizer_msg(e)
Arguments
e |
An error condition. |
Value
A single character string.
Force slow path in .to_cls_scalar()
Description
Force slow path in .to_cls_scalar()
Usage
.fast_false(x)
Arguments
x |
An object (ignored). |
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
x |
The vector to check. |
check_value |
The value to check against (e.g., a regex pattern). If
|
check_fn |
The function to use for checking. |
Value
An integer vector of failure locations, or NULL if there are no
failures or the check is skipped.
Find which elements of x match a spec applied independently to each element
Description
Find which elements of x match a spec applied independently to each element
Usage
.find_spec_matches(x, fn, x_arg, call)
Arguments
x |
The object to test. |
fn |
A stabilizer or coercion function, applied to each element of
|
x_arg |
( |
call |
|
Value
An integer vector of positions in x that match fn.
Convert a strptime()-style format string to a field-capturing regex
Description
Unlike .format_to_regex(), this keeps track of which calendar field each
capture group corresponds to, so the captured digits can be reassembled
regardless of the order in which the format places them (for example
"%m/%d/%Y" vs. "%Y-%m-%d").
Usage
.format_to_capture_regex(fmt)
Arguments
fmt |
( |
Value
A list with:
-
regex: the unanchored regex body (not yet wrapped in^/$). -
fields: a character vector naming the calendar field (one of"Y","m","d","H","M", or"S") captured by each group, in the order the groups appear inregex.
Convert a strptime()-style format string to a shape-checking regex
Description
Used to verify that a character vector's shape matches a candidate
format before handing it to as.Date(), since that function silently
ignores unmatched trailing characters rather than failing.
Usage
.format_to_regex(fmt)
Arguments
fmt |
( |
Value
A character(1) regular expression, anchored with ^ and $,
that matches strings shaped like fmt.
A wrapper for glue::glue with bracket delimiters
Description
A wrapper for glue::glue with bracket delimiters
Usage
.glue2(..., env = caller_env())
Arguments
... |
Arguments passed on to |
env |
The environment in which to evaluate the expressions. |
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
x |
The object to stabilize. |
regex |
|
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
x |
The object to check. |
allow_null |
( |
call |
|
Value
(logical(1)) 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
expr |
An R expression. |
Value
TRUE if expr is a covr counter call, FALSE otherwise.
Test for a length-1 date vector
Description
Test for a length-1 date vector
Usage
.is_scalar_date(x)
Arguments
x |
The object to check. |
Value
TRUE if x is a length-1 base::Date vector, else FALSE.
Test for a length-1 date-time vector
Description
Test for a length-1 date-time vector
Usage
.is_scalar_dttm(x)
Arguments
x |
The object to check. |
Value
TRUE if x is a length-1 base::POSIXct vector, else FALSE.
Test for a length-1 duration vector
Description
Test for a length-1 duration vector
Usage
.is_scalar_dur(x)
Arguments
x |
The object to check. |
Value
TRUE if x is a length-1 lubridate::Period vector, else
FALSE.
Test for a length-1 time-of-day vector
Description
Test for a length-1 time-of-day vector
Usage
.is_scalar_time(x)
Arguments
x |
The object to check. |
Value
TRUE if x is a length-1 hms::hms() vector, else FALSE.
Format matched specification labels for an error message
Description
When two or more matched labels are identical (e.g. the same function or
prototype passed more than once via ...), appends each label's position
in ... so the matches can be told apart; otherwise returns matched
unchanged, letting the caller quote it with {.val {matched}}.
Usage
.label_matched_specs(matched, matched_at)
Arguments
matched |
|
matched_at |
|
Value
A character vector, pre-quoted with position suffixes if matched
contains duplicates, or matched itself otherwise.
Guess a locale's conventional day/month order
Description
Guess a locale's conventional day/month order
Usage
.locale_date_order(locale_time)
Arguments
locale_time |
( |
Value
A length-2 character vector, either c("m", "d") (month before
day) or c("d", "m") (day before month).
Apply a spec to each element of x, failing on the first error
Description
Apply a spec to each element of x, failing on the first error
Usage
.map_each_fast(x, spec, x_arg, call)
Arguments
x |
The object to stabilize. |
spec |
A single stabilizer/coercion function applied to each element. |
x_arg |
( |
call |
|
Value
A list of per-element results, the same length as x.
Apply a spec to each element of x, collecting every failure
Description
Apply a spec to each element of x, collecting every failure
Usage
.map_each_safe(x, spec, x_arg, call)
Arguments
x |
The object to stabilize. |
spec |
A single stabilizer/coercion function applied to each element. |
x_arg |
( |
call |
|
Value
A list with elements:
-
out: per-element results (NULLat any failing location). -
errors: per-element error conditions (NULLat any successful location).
Construct the check_dupes expression
Description
Construct the check_dupes expression
Usage
.maybe_check_dupes(factory_args)
Arguments
factory_args |
Arguments passed into the factory. |
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
fn |
The function. |
fn_env |
The namespace environment of |
x_name |
The name used to refer to |
Value
"pkg::x_name" if x_name resolves to fn in fn_env, otherwise
x_name.
Copy x's names onto out, leaving out unnamed if x has none
Description
Copy x's names onto out, leaving out unnamed if x has none
Usage
.name_like(out, x)
Arguments
out |
|
x |
The object to stabilize. |
Value
out, named like x when x has any names.
Build a vector of lubridate::Period from component vectors
Description
lubridate::period() pairs a num vector elementwise against units,
rather than building one period per row, so it can't build a vector of
independent periods from parallel component vectors. This constructs the
Period object directly instead, which is vectorized over its slots.
Usage
.new_period_vec(year, month, day, hour, minute, second)
Arguments
year, month, day, hour, minute, second |
|
Value
A lubridate::Period vector the same length as the inputs.
Parse capture-group matches from .try_dttm_formats() into instants
Description
Parse capture-group matches from .try_dttm_formats() into instants
Usage
.parse_dttm_matches(matches, fields, tz)
Arguments
matches |
|
fields |
|
tz |
|
Value
A base::POSIXct vector (in tz), the same length as matches,
with NA at any position that describes an impossible date-time (such
as "2024-02-30").
Convert an RFC 3339 time-offset to a number of seconds
Description
Convert an RFC 3339 time-offset to a number of seconds
Usage
.parse_dttm_offset(x)
Arguments
x |
|
Value
A numeric vector of offsets from UTC, in seconds. Local time minus the offset gives the UTC instant.
Parse the regex captures from to_dttm.character() into instants
Description
Parse the regex captures from to_dttm.character() into instants
Usage
.parse_dttm_parts(matches)
Arguments
matches |
|
Value
A base::POSIXct vector (in UTC) the same length as matches, with
NA at any position that describes an impossible date-time (such as
"2024-02-30").
Parse the regex captures from to_dur.character()'s date/time form
Description
Parse the regex captures from to_dur.character()'s date/time form
Usage
.parse_dur_date_time_parts(matches)
Arguments
matches |
|
Value
A list with numeric year, month, day, hour, minute, and
second components (each 0 where the corresponding piece was absent),
and a logical valid vector that is FALSE where the match does not
describe a real duration (such as "P" or "PT", which have no components
at all).
Parse the regex captures from to_time.character() into seconds
Description
Parse the regex captures from to_time.character() into seconds
Usage
.parse_time_parts(matches)
Arguments
matches |
|
Value
A numeric vector the same length as matches, giving the UTC
time-of-day in seconds since midnight (always in [0, 86400)), or NA at
any position that describes an impossible time (such as "25:00:00Z").
Resolve a .named/.unnamed-style extra-element control argument
Description
Normalizes the three accepted forms of an extra-element control argument
(NULL/FALSE to forbid, TRUE to allow unchecked, or a stabilizer
function to validate) into either NULL (forbid), TRUE (allow), or the
stabilizer function (validate).
Usage
.resolve_extra_control(control, control_arg, call)
Arguments
control |
|
control_arg |
( |
call |
|
Value
NULL, TRUE, or a stabilizer function.
Check if two functions have the same definition
Description
Check if two functions have the same definition
Usage
.same_fn(x, y)
Arguments
x, y |
Functions to compare. |
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
... |
Arguments passed to methods. |
accepted_datetime_formats |
( |
additional_class |
( |
allow_na |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
allow_null |
( |
allow_zero_length |
( |
are_cls_ish_fn |
The |
call |
|
cast_fn |
|
check_cls_value_fn |
|
check_cls_value_fn_args |
|
coerce_character |
( |
coerce_factor |
( |
coerce_function |
( |
depth |
( |
due_to |
( |
exclusive_max_value |
( |
exclusive_min_value |
( |
failures |
|
is_rlang_cls_scalar |
|
levels |
|
max_characters |
( |
max_levels |
( |
max_size |
( |
max_value |
( |
message_env |
( |
min_characters |
( |
min_size |
( |
min_value |
( |
multiple_of |
( |
package |
( |
parent |
A parent condition, as you might create during a
|
regex |
|
simplify |
( |
spec |
|
to |
The target object for the coercion. |
to_class |
( |
to_cls_args |
|
to_cls_fn |
|
to_cls_scalar_args |
|
to_cls_scalar_fn |
|
to_na |
|
to_type_obj |
An empty object of the target type (e.g., |
tz |
( |
unique |
( |
x |
The object to stabilize. |
x_arg |
( |
x_class |
( |
Shared parameters for check functions
Description
Shared parameters for check functions
Arguments
x |
The object to check. |
Shared params for list helpers
Description
Shared params for list helpers
Arguments
element_specs |
|
is_extra_named |
|
named_spec |
A single stabilizer function, such as a |
nms |
|
Shared return for condition functions
Description
Shared return for condition functions
Value
NULL invisibly (called for side effects).
Simplify a list of per-element results into a common-type vector
Description
Combines out into an atomic vector when every element has size 1 and a
common type can be found; otherwise out is returned unchanged.
Usage
.simplify_each(out, simplify)
Arguments
out |
|
simplify |
( |
Value
out, simplified to an atomic vector when possible.
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
stabilizer |
( |
factory_args |
|
scalar |
( |
call |
|
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.
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,
unique = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
to_cls_fn |
|
... |
Arguments passed to methods. |
to_cls_args |
|
check_cls_value_fn |
|
check_cls_value_fn_args |
|
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
x_arg |
( |
call |
|
x_class |
( |
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
x |
The object to stabilize. |
to_cls_scalar_fn |
|
... |
Arguments passed to methods. |
to_cls_scalar_args |
|
check_cls_value_fn |
|
check_cls_value_fn_args |
|
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
x_arg |
( |
call |
|
x_class |
( |
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
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
x |
The object to stabilize. |
bad_casts |
|
levels |
|
to_na |
|
x_arg |
( |
call |
|
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
from_class |
( |
to_class |
( |
x_arg |
( |
call |
|
additional_msg |
( |
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
Value
NULL invisibly (called for side effects).
Signal an error when a spec fails in stabilize_all_of()
Description
Signal an error when a spec fails in stabilize_all_of()
Usage
.stop_cant_stabilize_all_of(error, x_arg, call)
Arguments
error |
|
x_arg |
( |
call |
|
Value
Does not return; throws an error.
Signal a combined error when no function succeeds
Description
Signal a combined error when no function succeeds
Usage
.stop_cant_stabilize_any_of(errors, x_arg, call)
Arguments
errors |
|
x_arg |
( |
call |
|
Value
Does not return; throws an error.
Signal a combined error when any element fails its spec
Description
Signal a combined error when any element fails its spec
Usage
.stop_cant_stabilize_each(errors, locations, x_arg, x_class, call)
Arguments
errors |
|
locations |
|
x_arg |
( |
x_class |
( |
call |
|
Value
Does not return; throws an error.
Signal an error when zero, or more than one, specs match in stabilize_one_of()/to_one_of()
Description
Signal an error when zero, or more than one, specs match in stabilize_one_of()/to_one_of()
Usage
.stop_cant_stabilize_one_of(errors, matched, matched_at, x_arg, call)
Arguments
errors |
|
matched |
|
matched_at |
|
x_arg |
( |
call |
|
Value
Does not return; throws an error.
Abort because an object must not be a function
Description
Abort because an object must not be a function
Usage
.stop_function(x_arg, call)
Arguments
x_arg |
( |
call |
|
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
x_expr |
The expression from the quosure. |
x_class |
( |
x_arg |
( |
call |
|
Abort with an "incompatible type" message
Description
Abort with an "incompatible type" message
Usage
.stop_incompatible(
x,
x_class,
to,
failures,
due_to,
x_arg,
call,
parent = NULL,
...
)
Arguments
x |
The object to stabilize. |
x_class |
( |
to |
The target object for the coercion. |
failures |
|
due_to |
( |
x_arg |
( |
call |
|
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
Value
NULL invisibly (called for side effects).
Signal an error when specs in stabilize_all_of() disagree
Description
Signal an error when specs in stabilize_all_of() disagree
Usage
.stop_inconsistent_all_of(x_arg, call)
Arguments
x_arg |
( |
call |
|
Value
Does not return; throws an error.
Signal an error when x matches a spec forbidden by assert_not()
Description
Signal an error when x matches a spec forbidden by assert_not()
Usage
.stop_matched_spec(spec_label, x_arg, call)
Arguments
spec_label |
|
x_arg |
( |
call |
|
Value
Does not return; throws an error.
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
msg |
|
x_arg |
( |
call |
|
additional_msg |
|
subclass |
( |
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
Value
NULL invisibly (called for side effects).
Abort because an object must not be NULL
Description
Abort because an object must not be NULL
Usage
.stop_null(x_arg, call, parent = NULL, ...)
Arguments
x_arg |
( |
call |
|
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
expr |
An R expression (e.g. as returned by |
Value
The expression with all covr counter blocks removed.
An empty time object for error messages
Description
object_type() renders an hms::hms() as "hms", but the time family uses
"time" in its coercion classes and messages, to match the
to_time()/stabilize_time() function names. This returns an empty object
that renders as "time" so error subclasses read
<stbl-error-incompatible_values-time>.
Usage
.time_type_obj()
Value
A zero-length object whose object_type() is "time".
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
Value
The object 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
x |
The object to stabilize. |
to_cls_fn |
|
to_cls_args |
|
to_class |
( |
coerce_factor |
( |
x_arg |
( |
call |
|
x_class |
( |
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
x |
The object to stabilize. |
is_rlang_cls_scalar |
|
to_cls_fn |
|
to_cls_args |
|
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
x as a scalar of the target class.
Coerce to date, trying accepted_datetime_formats for character input
Description
Used by stabilize_date() in place of to_date(), so that character input
can be tried against a list of accepted_datetime_formats rather than only
the strict RFC 3339 shape that to_date() enforces. Non-character input
(and factors, once converted to character) is delegated to to_date()
unchanged.
Usage
.to_date_locale(
x,
...,
accepted_datetime_formats,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a base::Date vector.
Coerce to length-1 date, trying accepted_datetime_formats
Description
The scalar counterpart of .to_date_locale(), used by
stabilize_date_scalar() in place of to_date_scalar().
Usage
.to_date_locale_scalar(
x,
...,
accepted_datetime_formats,
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
accepted_datetime_formats |
( |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::Date vector.
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
x |
The object to stabilize. |
x_expr |
|
x_arg |
( |
call |
|
x_class |
( |
... |
Arguments passed to methods. |
Value
A one-column data frame.
Coerce to date-time, trying accepted_datetime_formats for character input
Description
Used by stabilize_dttm() in place of to_dttm(), so that character input
can be tried against a list of accepted_datetime_formats (with an
optional UTC offset) rather than only the strict RFC 3339 shape that
to_dttm() enforces. Non-character input (and factors, once converted to
character) is delegated to to_dttm() unchanged.
Usage
.to_dttm_locale(
x,
...,
tz,
accepted_datetime_formats,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a base::POSIXct vector.
Coerce to length-1 date-time, trying accepted_datetime_formats
Description
The scalar counterpart of .to_dttm_locale(), used by
stabilize_dttm_scalar() in place of to_dttm_scalar().
Usage
.to_dttm_locale_scalar(
x,
...,
tz,
accepted_datetime_formats,
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
accepted_datetime_formats |
( |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::POSIXct vector.
Ensure an object is NULL
Description
Ensure an object is NULL
Usage
.to_null(x, allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())
Arguments
x |
The object to stabilize. |
allow_null |
( |
x_arg |
( |
call |
|
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
x |
The object to stabilize. |
cast_fn |
|
to_type_obj |
An empty object of the target type (e.g., |
x_arg |
( |
call |
|
x_class |
( |
Value
x coerced to the target class.
Try candidate date formats against a character vector
Description
Tries each format in formats, in order, and returns the first one that
parses every non-NA element of x without failure. If none succeed for
every element, returns the result of the first format tried, so that error
messages describe a concrete (if incomplete) failure rather than an
arbitrary one.
Usage
.try_date_formats(x, formats)
Arguments
x |
|
formats |
|
Value
A list with parsed (a base::Date vector) and failures (a
logical vector, the same length as x, TRUE where an element could not
be parsed with the chosen format).
Try candidate date-time formats against a character vector
Description
Like .try_date_formats(), but for date-time strings, with an optional
trailing UTC offset ("Z" or a numeric offset such as "+05:00").
Elements with an offset are converted using that offset; elements without
one are treated as wall-clock time in tz.
Usage
.try_dttm_formats(x, formats, tz)
Arguments
x |
|
formats |
|
tz |
|
Value
A list with parsed (a base::POSIXct vector, in tz) and
failures (a logical vector, the same length as x).
Try every item, requiring exactly one to succeed
Description
Try every item, requiring exactly one to succeed
Usage
.try_exactly_one(items, run_one, labels, x_arg, call)
Arguments
items |
|
run_one |
|
labels |
|
x_arg |
( |
call |
|
Value
The result of the single item that does not throw an error.
Try each function in sequence, returning the first success
Description
Try each function in sequence, returning the first success
Usage
.try_fns(x, fns, x_arg, call)
Arguments
x |
The value to test. |
fns |
|
x_arg |
( |
call |
|
Value
The result of the first function that does not throw an error.
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
.x |
The object to stabilize. |
nms |
|
is_extra_named |
|
named_spec |
A single stabilizer function, such as a |
.x_arg |
( |
.call |
|
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,
.required,
.allow_duplicate_names,
.x_arg,
.call
)
Arguments
.x |
The object to stabilize. |
... |
Named stabilizer functions, such as |
.named |
Controls how named elements of
|
.required |
|
.allow_duplicate_names |
( |
.x_arg |
( |
.call |
|
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, .required, .x_arg, .call)
Arguments
.x |
The object to stabilize. |
element_specs |
|
nms |
|
.required |
|
.x_arg |
( |
.call |
|
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
.x |
The object to stabilize. |
.unnamed |
Controls how unnamed elements of
|
.x_arg |
( |
.call |
|
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
x |
The object to check. |
... |
Arguments passed to methods. |
depth |
( |
Value
are_chr_ish() returns a logical vector with the same length as the
input. is_chr_ish() returns a length-1 logical (TRUE or FALSE) for
the entire vector.
See Also
Other character functions:
specify_chr(),
stabilize_chr(),
stabilize_chr_scalar(),
to(),
to_chr(),
to_chr_scalar()
Other check functions:
are_dbl_ish(),
are_fct_ish(),
are_fn_ish(),
are_int_ish(),
are_lgl_ish()
Examples
are_chr_ish(letters)
is_chr_ish(letters)
are_chr_ish(1:10)
is_chr_ish(1:10)
are_chr_ish(list("a", 1, TRUE))
is_chr_ish(list("a", 1, TRUE))
are_chr_ish(list("a", 1, list(1, 2)))
is_chr_ish(list("a", 1, list(1, 2)))
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
x |
The object to check. |
... |
Arguments passed to methods. |
coerce_character |
( |
coerce_factor |
( |
depth |
( |
Value
are_dbl_ish() returns a logical vector with the same length as the
input. is_dbl_ish() returns a length-1 logical (TRUE or FALSE) for
the entire vector.
See Also
Other double functions:
specify_dbl(),
stabilize_dbl(),
stabilize_dbl_scalar(),
to(),
to_dbl(),
to_dbl_scalar()
Other check functions:
are_chr_ish(),
are_fct_ish(),
are_fn_ish(),
are_int_ish(),
are_lgl_ish()
Examples
are_dbl_ish(c(1.0, 2.2, 3.14))
is_dbl_ish(c(1.0, 2.2, 3.14))
are_dbl_ish(1:3)
is_dbl_ish(1:3)
are_dbl_ish(c("1.1", "2.2", NA))
is_dbl_ish(c("1.1", "2.2", NA))
are_dbl_ish(c("a", "1.0"))
is_dbl_ish(c("a", "1.0"))
are_dbl_ish(list(1, "2.2", "c"))
is_dbl_ish(list(1, "2.2", "c"))
are_dbl_ish(c(1 + 1i, 1 + 0i, NA))
is_dbl_ish(c(1 + 1i, 1 + 0i, NA))
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
x |
The object to check. |
... |
Arguments passed to methods. |
levels |
|
to_na |
|
max_levels |
( |
depth |
( |
Value
are_fct_ish() returns a logical vector with the same length as the
input. is_fct_ish() returns a length-1 logical (TRUE or FALSE) for
the entire vector.
See Also
Other factor functions:
specify_fct(),
stabilize_fct(),
stabilize_fct_scalar(),
to(),
to_fct(),
to_fct_scalar()
Other check functions:
are_chr_ish(),
are_dbl_ish(),
are_fn_ish(),
are_int_ish(),
are_lgl_ish()
Examples
# When `levels` is `NULL`, atomic vectors are fct_ish, but nested lists are
# not.
are_fct_ish(c("a", 1, NA))
is_fct_ish(c("a", 1, NA))
are_fct_ish(list("a", list("b", "c")))
is_fct_ish(list("a", list("b", "c")))
# When `levels` is specified, values must be in `levels` or `to_na`.
are_fct_ish(c("a", "b", "c"), levels = c("a", "b"))
is_fct_ish(c("a", "b", "c"), levels = c("a", "b"))
# The `to_na` argument allows some values to be treated as `NA`.
are_fct_ish(c("a", "b", "z"), levels = c("a", "b"), to_na = "z")
is_fct_ish(c("a", "b", "z"), levels = c("a", "b"), to_na = "z")
# `max_levels` limits distinct non-`NA` values across the whole vector.
is_fct_ish(c("a", "b", "c"), max_levels = 2)
# Factors are also checked against the specified levels.
are_fct_ish(factor(c("a", "b", "c")), levels = c("a", "b"))
is_fct_ish(factor(c("a", "b", "c")), levels = c("a", "b"))
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
x |
The object to check. |
... |
Arguments passed to methods. |
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-
NAcharacter 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
x |
The object to check. |
... |
Arguments passed to methods. |
coerce_character |
( |
coerce_factor |
( |
depth |
( |
Value
are_int_ish() returns a logical vector with the same length as the
input. is_int_ish() returns a length-1 logical (TRUE or FALSE) for
the entire vector.
See Also
Other integer functions:
specify_int(),
stabilize_int(),
stabilize_int_scalar(),
to(),
to_int(),
to_int_scalar()
Other check functions:
are_chr_ish(),
are_dbl_ish(),
are_fct_ish(),
are_fn_ish(),
are_lgl_ish()
Examples
are_int_ish(1:4)
is_int_ish(1:4)
are_int_ish(c(1.0, 2.0, 3.00000))
is_int_ish(c(1.0, 2.0, 3.00000))
are_int_ish(c("1.0", "2.0", "3.00000"))
is_int_ish(c("1.0", "2.0", "3.00000"))
are_int_ish(c(1, 2.2, NA))
is_int_ish(c(1, 2.2, NA))
are_int_ish(c("1", "1.0", "1.1", "a"))
is_int_ish(c("1", "1.0", "1.1", "a"))
are_int_ish(factor(c("1", "a")))
is_int_ish(factor(c("1", "a")))
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
x |
The object to check. |
... |
Arguments passed to methods. |
depth |
( |
Value
are_lgl_ish() returns a logical vector with the same length as the
input. is_lgl_ish() returns a length-1 logical (TRUE or FALSE) for
the entire vector.
See Also
Other logical functions:
specify_lgl(),
stabilize_lgl(),
stabilize_lgl_scalar(),
to(),
to_lgl(),
to_lgl_scalar()
Other check functions:
are_chr_ish(),
are_dbl_ish(),
are_fct_ish(),
are_fn_ish(),
are_int_ish()
Examples
are_lgl_ish(c(TRUE, FALSE, NA))
is_lgl_ish(c(TRUE, FALSE, NA))
are_lgl_ish(c(1, 0, 1.0, NA))
is_lgl_ish(c(1, 0, 1.0, NA))
are_lgl_ish(c("T", "F", "TRUE", "FALSE", "true", "false", "1", "0"))
is_lgl_ish(c("T", "F", "TRUE", "FALSE", "true", "false", "1", "0"))
are_lgl_ish(c("T", "F", "a", "1.1"))
is_lgl_ish(c("T", "F", "a", "1.1"))
are_lgl_ish(factor(c("T", "a")))
is_lgl_ish(factor(c("T", "a")))
are_lgl_ish(list(TRUE, 0, "F", "a"))
is_lgl_ish(list(TRUE, 0, "F", "a"))
Require that x contains a number of elements matching a specification
Description
assert_contains() applies spec to each element of x independently
and counts how many elements match. It returns x unchanged if that count
falls between min_matches and max_matches (inclusive), and errors
otherwise.
Usage
assert_contains(
x,
spec,
...,
min_matches = 1,
max_matches = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
spec |
|
... |
Arguments passed to methods. |
min_matches |
( |
max_matches |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
x, unchanged, if the number of elements of x matching spec
is between min_matches and max_matches, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-too_few_matches>when fewer thanmin_matcheselements matchspec. -
<stbl-error-too_many_matches>when more thanmax_matcheselements matchspec.
See Also
Other stabilization functions:
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# By default, at least 1 element must match spec
assert_contains(list("1", "a", "b"), stabilize_int)
# Require at least 2 matching elements
assert_contains(list("1", "2", "a"), stabilize_int, min_matches = 2)
# Errors because no elements are int-ish
try(assert_contains(list("a", "b"), stabilize_int))
# Errors because too many elements are int-ish
try(assert_contains(list("1", "2", "3"), stabilize_int, max_matches = 2))
# spec is applied to each element, not to x as a whole, so a scalar spec
# like stabilize_int_scalar() still matches every element of a list
assert_contains(
list(1L, 2L, 3L),
stabilize_int_scalar,
min_matches = 2,
max_matches = 3
)
# Use min_matches = 0 to check only an upper bound on the number of matches
assert_contains(
list("1", "a", "b"),
stabilize_int,
min_matches = 0,
max_matches = 1
)
Require a value not to match a specification
Description
assert_not() is the inverse of a single specification: it errors when x
would be accepted by spec, and returns x unchanged otherwise.
Usage
assert_not(
x,
spec,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
spec |
A single stabilizer function, |
... |
Reserved for future use; must be empty. |
x_arg |
( |
call |
|
x_class |
( |
Value
x, unchanged, if x does not match spec, or an error
condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and
<stbl-error-matched_spec> when x matches spec.
See Also
Other stabilization functions:
assert_contains(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
assert_not("a", specify_int())
assert_not(1.5, stabilize_int)
# Errors because "1" is int-ish, even though it isn't literally an integer
try(assert_not("1", specify_int()))
# Errors because stabilize_int() succeeds outright on 1L
try(assert_not(1L, stabilize_int))
Require a value to be non-NULL
Description
assert_present() validates that a value is not NULL. Any non-NULL
value passes through unchanged. This is useful as an element specification
in stabilize_lst() when you need to require a named element without
imposing any type constraints on its value.
Usage
assert_present(
x,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
x_arg |
( |
call |
|
x_class |
( |
Value
The value, unchanged.
See Also
Other list functions:
specify_lst(),
stabilize_lst(),
to(),
to_lst()
Other stabilization functions:
assert_contains(),
assert_not(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
assert_present("any value")
assert_present(list(1, 2, 3))
try(assert_present(NULL))
# Use as a named element spec in stabilize_lst()
stabilize_lst(list(data = mtcars), data = assert_present)
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
object |
An expression that is expected to throw an error. |
package |
( |
... |
|
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
object |
An expression that is expected to throw an error. |
package |
( |
... |
|
transform |
( |
variant |
( |
env |
( |
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
object |
An expression that is expected to throw a message. |
package |
( |
... |
|
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
object |
An expression that is expected to throw a message. |
package |
( |
... |
|
transform |
( |
variant |
( |
env |
( |
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
object |
An expression that is expected to throw a warning. |
package |
( |
... |
|
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
object |
An expression that is expected to throw a warning. |
package |
( |
... |
|
transform |
( |
variant |
( |
env |
( |
Value
The result of testthat::expect_snapshot(), invisibly.
Ignore a stbl error class
Description
Silences a stbl error with the specified subclass. Other errors
(including other stbl errors) are not caught and propagate normally. See
the documentation of each stabilize_*() or to_*() function for the types
of errors it throws.
Usage
ignore_stbl_error(expr, subclass = character())
Arguments
expr |
An expression to evaluate. |
subclass |
( |
Value
The result of expr if no matching error is thrown, or NULL
if a matching stbl error is caught.
Examples
ignore_stbl_error(to_chr(data.frame()), subclass = c("coerce", "character"))
ignore_stbl_error(to_chr("hello"), subclass = c("coerce", "character"))
# Omit subclass to catch any stbl error
ignore_stbl_error(to_chr(data.frame()))
Injection operator for defused arguments
Description
Injection operator for defused arguments
Determine locale-aware date and date-time formats
Description
Returns an ordered set of strptime()-style format strings, used as the
default value of accepted_datetime_formats in stabilize_date(),
stabilize_dttm(), and their siblings. Character input is tried against
each format in turn, in order, until one of them parses every element (see
those functions for details).
Usage
locale_datetime_formats(locale_time = Sys.getlocale("LC_TIME"))
Arguments
locale_time |
( |
Value
A character() vector of strptime()-style format strings,
always starting with "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", and
"%Y-%m-%d" (in that order), followed by the locale's conventional
day/month order with "/" and then "-" separators (each listed with,
then without, a " %H:%M:%S" suffix).
See Also
Other date functions:
specify_date(),
stabilize_date(),
stabilize_date_scalar(),
to_date(),
to_date_scalar()
Other datetime functions:
specify_dttm(),
stabilize_dttm(),
stabilize_dttm_scalar(),
to_dttm(),
to_dttm_scalar()
Examples
locale_datetime_formats("en_US.UTF-8")
locale_datetime_formats("en_GB.UTF-8")
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
x |
An object to test. |
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
package |
( |
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
package |
( |
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
package |
( |
message |
( |
subclass |
( |
call |
|
message_env |
( |
parent |
A parent condition, as you might create during a
|
... |
Additional parameters passed to |
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
Create a regex matching rule
Description
Attach a standardized error message to a regex pattern. By default, the
message will be "must match the regex pattern {regex}". If the input
regex has a negate attribute set to TRUE (set automatically by
regex_must_not_match()), the message will instead be "must not match...".
This message can be used with stabilize_chr() and stabilize_chr_scalar().
Usage
regex_must_match(regex)
regex_must_not_match(regex)
Arguments
regex |
|
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]")
Replace a stbl error with a custom message
Description
Catches a stbl error with the specified subclass and replaces its
message with a new one. Use this to provide more context-specific error
messages when calling stbl functions inside your own functions. See
the documentation of each stabilize_*() or to_*() function for the types
of errors it throws.
Usage
replace_stbl_error(
expr,
message,
subclass = character(),
additional_class = character(),
message_env = caller_env()
)
Arguments
expr |
An expression to evaluate. |
message |
( |
subclass |
( |
additional_class |
( |
message_env |
( |
Value
The result of expr, or an error with the replacement message if
a matching {stbl} error is thrown.
Examples
my_fn <- function(x) {
x <- to_chr(x) |>
replace_stbl_error(
message = "{.arg x} must be a character vector of widgets",
subclass = c("coerce", "character")
)
}
try(my_fn(data.frame()))
# Specify a class to check for expected errors with testthat::expect_error()
my_fn2 <- function(x) {
x <- to_chr(x) |>
replace_stbl_error(
message = "{.arg x} must be a character vector of widgets",
subclass = c("coerce", "character"),
additional_class = "mypkg-error-bad_widget"
)
}
try(my_fn2(data.frame()))
# Omit subclass to catch any stbl error
my_fn3 <- function(x) {
x <- to_chr(x) |>
replace_stbl_error(message = "{.arg x} must be a character vector of widgets")
}
try(my_fn3(data.frame()))
Create a specified all-of stabilizer function
Description
specify_all_of() creates a function that will call stabilize_all_of()
with the provided specs. specify_all_of()'s function requires that x
satisfy every provided spec, and that all specs agree on the coerced
result.
Usage
specify_all_of(...)
Arguments
... |
Unnamed stabilizer functions, forwarded to
|
Value
A function of class "stbl_specified_fn" that calls
stabilize_all_of() with the provided specs. The generated function will
also accept ... for additional unnamed specs to pass to
stabilize_all_of(). You can copy/paste the body of the resulting
function if you want to provide additional context or functionality.
See Also
Other specification functions:
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_a_then_b <- specify_all_of(
specify_chr(regex = "^a"),
specify_chr(regex = "b$")
)
stabilize_a_then_b("ab")
try(stabilize_a_then_b("ba"))
Create a specified any-of stabilizer function
Description
specify_any_of() creates a function that will call stabilize_any_of()
with the provided specs. specify_any_of()'s function tries each spec in
order and returns the result of the first one that succeeds.
Usage
specify_any_of(...)
Arguments
... |
Unnamed stabilizer / |
Value
A function of class "stbl_specified_fn" that calls
stabilize_any_of() with the provided specs. The generated function will
also accept ... for additional unnamed specs to pass to
stabilize_any_of(). You can copy/paste the body of the resulting
function if you want to provide additional context or functionality.
See Also
Other specification functions:
specify_all_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_int_or_chr <- specify_any_of(specify_int(), specify_chr())
stabilize_int_or_chr(1L)
stabilize_int_or_chr("a")
try(stabilize_int_or_chr(TRUE))
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,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL
)
specify_chr_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL
)
specify_character(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL
)
specify_character_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_characters |
( |
max_characters |
( |
regex |
|
allowed_values |
A vector of permitted values (coerced to the target
type). |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_chr() or stabilize_chr_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_chr() or stabilize_chr_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other character functions:
are_chr_ish(),
stabilize_chr(),
stabilize_chr_scalar(),
to(),
to_chr(),
to_chr_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_email <- specify_chr(regex = "^[^@]+@[^@]+\\.[^@]+$")
stabilize_email("stbl@example.com")
try(stabilize_email("not-an-email-address"))
Create a specified date stabilizer function
Description
specify_date() creates a function that will call stabilize_date() with
the provided arguments. specify_date_scalar() creates a function that will
call stabilize_date_scalar() with the provided arguments.
Usage
specify_date(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
specify_date_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
Arguments
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_date() or stabilize_date_scalar() with the provided
arguments. The generated function will also accept ... for additional
arguments to pass to stabilize_date() or stabilize_date_scalar(). You
can copy/paste the body of the resulting function if you want to provide
additional context or functionality.
See Also
Other date functions:
locale_datetime_formats(),
stabilize_date(),
stabilize_date_scalar(),
to_date(),
to_date_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_recent <- specify_date(min_value = "2000-01-01")
stabilize_recent("2024-01-01")
try(stabilize_recent("1999-12-31"))
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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_dbl_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_double(
allow_null = TRUE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_double_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_dbl() or stabilize_dbl_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_dbl() or stabilize_dbl_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other double functions:
are_dbl_ish(),
stabilize_dbl(),
stabilize_dbl_scalar(),
to(),
to_dbl(),
to_dbl_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_3_to_5 <- specify_dbl(min_value = 3, max_value = 5)
stabilize_3_to_5(c(3.3, 4.4, 5))
try(stabilize_3_to_5(c(1:6)))
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,
.allow_zero_length = TRUE,
.required = ...names()
)
specify_data_frame(
...,
.extra_cols = NULL,
.col_names = NULL,
.min_rows = NULL,
.max_rows = NULL,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.required = ...names()
)
Arguments
... |
Named stabilizer functions, such as |
.extra_cols |
Controls how columns of
|
.col_names |
|
.min_rows |
( |
.max_rows |
( |
.allow_null |
( |
.allow_zero_length |
( |
.required |
|
Value
A function of class "stbl_specified_fn" that calls
stabilize_df() with the provided arguments. The generated function will
also accept ... for additional named column specifications to pass to
stabilize_df(). You can copy/paste the body of the resulting function if
you want to provide additional context or functionality.
See Also
Other data frame functions:
stabilize_df(),
to(),
to_df()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_person_df <- specify_df(
name = specify_chr_scalar(allow_na = FALSE),
age = specify_int_scalar(allow_na = FALSE),
.extra_cols = assert_present
)
stabilize_person_df(data.frame(name = "Alice", age = 30L, score = 99.5))
try(stabilize_person_df(data.frame(name = "Alice")))
# Mark a column as optional via .required
stabilize_person_df2 <- specify_df(
name = specify_chr_scalar(allow_na = FALSE),
age = specify_int_scalar(allow_na = FALSE),
.required = "name"
)
stabilize_person_df2(data.frame(name = "Alice"))
Create a specified datetime stabilizer function
Description
specify_dttm() creates a function that will call stabilize_dttm() with
the provided arguments. specify_dttm_scalar() creates a function that will
call stabilize_dttm_scalar() with the provided arguments.
specify_datetime() is a synonym of specify_dttm(), and
specify_datetime_scalar() is a synonym of specify_dttm_scalar().
Usage
specify_dttm(
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
specify_dttm_scalar(
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
specify_datetime(
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
specify_datetime_scalar(
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats()
)
Arguments
tz |
( |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_dttm() or stabilize_dttm_scalar() with the provided
arguments. The generated function will also accept ... for additional
arguments to pass to stabilize_dttm() or stabilize_dttm_scalar(). You
can copy/paste the body of the resulting function if you want to provide
additional context or functionality.
See Also
Other datetime functions:
locale_datetime_formats(),
stabilize_dttm(),
stabilize_dttm_scalar(),
to_dttm(),
to_dttm_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_recent <- specify_dttm(min_value = "2000-01-01T00:00:00Z")
stabilize_recent("2024-01-01T00:00:00Z")
try(stabilize_recent("1999-12-31T00:00:00Z"))
Create a specified duration stabilizer function
Description
specify_dur() creates a function that will call stabilize_dur() with the
provided arguments. specify_dur_scalar() creates a function that will call
stabilize_dur_scalar() with the provided arguments. specify_duration() is
a synonym of specify_dur(), and specify_duration_scalar() is a synonym of
specify_dur_scalar().
Usage
specify_dur(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
specify_dur_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
specify_duration(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
specify_duration_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_dur() or stabilize_dur_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_dur() or stabilize_dur_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other duration functions:
stabilize_dur(),
stabilize_dur_scalar(),
to_dur(),
to_dur_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_short <- specify_dur(max_value = "P1D")
stabilize_short("PT12H")
try(stabilize_short("P2D"))
Create a specified each stabilizer function
Description
specify_each() creates a function that will call stabilize_each() with
the provided spec, letting an element-wise spec be reused and nested
inside other specify_*()/stabilize_*() calls.
Usage
specify_each(spec)
Arguments
spec |
|
Value
A function of class "stbl_specified_fn" that calls
stabilize_each() with the provided spec. The generated function will
also accept simplify and ... to pass to stabilize_each(). You can
copy/paste the body of the resulting function if you want to provide
additional context or functionality.
See Also
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_ints <- specify_each(stabilize_int)
stabilize_ints(list("1", "2", "3"))
try(stabilize_ints(list("1", "a")))
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
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
levels |
|
to_na |
|
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_fct() or stabilize_fct_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_fct() or stabilize_fct_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other factor functions:
are_fct_ish(),
stabilize_fct(),
stabilize_fct_scalar(),
to(),
to_fct(),
to_fct_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_lowercase_letter <- specify_fct(levels = letters)
stabilize_lowercase_letter(c("s", "t", "b", "l"))
try(stabilize_lowercase_letter("A"))
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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_int_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_integer(
allow_null = TRUE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
specify_integer_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_int() or stabilize_int_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_int() or stabilize_int_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other integer functions:
are_int_ish(),
stabilize_int(),
stabilize_int_scalar(),
to(),
to_int(),
to_int_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_lgl(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_3_to_5 <- specify_int(min_value = 3, max_value = 5)
stabilize_3_to_5(c(3:5))
try(stabilize_3_to_5(c(1:6)))
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,
allowed_values = NULL
)
specify_lgl_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
allowed_values = NULL
)
specify_logical(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
allowed_values = NULL
)
specify_logical_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
allowed_values = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_lgl() or stabilize_lgl_scalar() with the provided arguments.
The generated function will also accept ... for additional arguments to
pass to stabilize_lgl() or stabilize_lgl_scalar(). You can copy/paste
the body of the resulting function if you want to provide additional
context or functionality.
See Also
Other logical functions:
are_lgl_ish(),
stabilize_lgl(),
stabilize_lgl_scalar(),
to(),
to_lgl(),
to_lgl_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lst(),
specify_one_of(),
specify_time()
Examples
stabilize_few_lgl <- specify_lgl(max_size = 5)
stabilize_few_lgl(c(TRUE, "False", TRUE))
try(stabilize_few_lgl(rep(TRUE, 10)))
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,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names()
)
specify_list(
...,
.named = NULL,
.unnamed = NULL,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names()
)
Arguments
... |
Named stabilizer functions, such as |
.named |
Controls how named elements of
|
.unnamed |
Controls how unnamed elements of
|
.unique |
( |
.allow_null |
( |
.allow_zero_length |
( |
.min_size |
( |
.max_size |
( |
.required |
|
Value
A function of class "stbl_specified_fn" that calls
stabilize_lst() with the provided arguments. The generated function will
also accept ... for additional named element specifications to pass to
stabilize_lst(). You can copy/paste the body of the resulting function if
you want to provide additional context or functionality.
See Also
Other list functions:
assert_present(),
stabilize_lst(),
to(),
to_lst()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_one_of(),
specify_time()
Examples
stabilize_config <- specify_lst(
name = specify_chr_scalar(allow_na = FALSE),
version = stabilize_int_scalar,
debug = specify_lgl_scalar(allow_na = FALSE),
.unnamed = stabilize_chr_scalar
)
stabilize_config(list(name = "myapp", version = 1L, debug = FALSE, "extra"))
try(
stabilize_config(
list(name = "myapp", version = 1L, debug = FALSE, c("a", "b"))
)
)
# Mark some elements as optional via .required
stabilize_settings <- specify_lst(
name = specify_chr_scalar(),
nickname = specify_chr_scalar(),
.required = "name"
)
stabilize_settings(list(name = "Alice"))
Create a specified one-of stabilizer function
Description
specify_one_of() creates a function that will call stabilize_one_of()
with the provided specs. specify_one_of()'s function requires that
exactly one of the provided specs succeeds.
Usage
specify_one_of(...)
Arguments
... |
Unnamed stabilizer / |
Value
A function of class "stbl_specified_fn" that calls
stabilize_one_of() with the provided specs. The generated function will
also accept ... for additional unnamed specs to pass to
stabilize_one_of(). You can copy/paste the body of the resulting
function if you want to provide additional context or functionality.
See Also
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_time()
Examples
stabilize_int_xor_chr <- specify_one_of(stabilize_int, stabilize_chr)
stabilize_int_xor_chr("a")
try(stabilize_int_xor_chr("1"))
Create a specified time-of-day stabilizer function
Description
specify_time() creates a function that will call stabilize_time() with
the provided arguments. specify_time_scalar() creates a function that will
call stabilize_time_scalar() with the provided arguments.
Usage
specify_time(
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
specify_time_scalar(
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL
)
Arguments
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
allow_zero_length |
( |
Value
A function of class "stbl_specified_fn" that calls
stabilize_time() or stabilize_time_scalar() with the provided
arguments. The generated function will also accept ... for additional
arguments to pass to stabilize_time() or stabilize_time_scalar(). You
can copy/paste the body of the resulting function if you want to provide
additional context or functionality.
See Also
Other time functions:
stabilize_time(),
stabilize_time_scalar(),
to_time(),
to_time_scalar()
Other specification functions:
specify_all_of(),
specify_any_of(),
specify_chr(),
specify_date(),
specify_dbl(),
specify_df(),
specify_dttm(),
specify_dur(),
specify_each(),
specify_fct(),
specify_int(),
specify_lgl(),
specify_lst(),
specify_one_of()
Examples
stabilize_afternoon <- specify_time(min_value = "12:00:00Z")
stabilize_afternoon("13:00:00Z")
try(stabilize_afternoon("06:00:00Z"))
Try to coerce or validate x as all of several specs
Description
stabilize_all_of() validates and coerces x by applying every function in
... to x, independently. x must satisfy every spec, and all specs must
agree on the coerced result; if any spec fails, or specs disagree on the
coerced value, an informative error is thrown. stabilise_all_of() is a
synonym.
Usage
stabilize_all_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_all_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Unnamed stabilizer functions, such as |
x_arg |
( |
call |
|
x_class |
( |
Value
x coerced or validated by every function in ..., or an error
condition with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-empty_specs>when no functions are supplied in.... -
<stbl-error-named_spec>when any element of...is named. -
<stbl-error-cant_stabilize_all_of>when any provided function fails. -
<stbl-error-inconsistent_all_of>when every function succeeds, but they don't all produce the same coerced value.
See Also
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# Returns x unchanged when all functions succeed
stabilize_all_of(1L, stabilize_int, stabilize_int_scalar)
# Each spec is applied to the original x, independently
stabilize_all_of("ab", specify_chr(regex = "^a"), specify_chr(regex = "b$"))
# Errors with a combined message when a spec fails
try(stabilize_all_of("a", stabilize_int, stabilize_chr))
# Errors because each spec sees the original "1" (a string); the second
# spec would succeed on 1L, but doesn't get the chance to see it
try(stabilize_all_of("1", stabilize_int, specify_dbl(coerce_character = FALSE)))
# Errors when specs succeed but disagree on the coerced value
# (stabilize_int() keeps 1L an integer; specify_dbl() makes it a double)
try(stabilize_all_of(1L, stabilize_int, specify_dbl()))
Try to coerce or validate x as one of several types
Description
stabilize_any_of() attempts to validate and coerce x using
each function in ... in order. It returns the result of the first
function that succeeds. If all functions fail, an informative error that
combines the individual failure messages is thrown. stabilise_any_of() is
a synonym.
to_any_of() is analogous to to(): it tries to coerce x to each type
given in ... (as a prototype such as integer() or character()) and
returns the first successful result.
Usage
stabilize_any_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_any_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
to_any_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
For |
x_arg |
( |
call |
|
x_class |
( |
Value
x coerced or validated by the first successful function or
prototype in ..., or an error condition with classes <stbl-error>,
<stbl-condition>, <rlang_error>, <error>, <condition>, and a
specific class by failure mode:
-
<stbl-error-empty_specs>when no functions are supplied in.... -
<stbl-error-named_spec>when any element of...is named. -
<stbl-error-cant_stabilize_any_of>when all provided functions fail.
See Also
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# Returns x unchanged when the first function succeeds
stabilize_any_of(1L, stabilize_int, stabilize_chr)
# Falls through to stabilize_chr when stabilize_int fails
stabilize_any_of("a", stabilize_int, stabilize_chr)
# Coerces via the first matching function ("1" -> 1L)
stabilize_any_of("1", stabilize_int, stabilize_chr)
# A mixed list falls through to stabilize_chr because "a" can't be integer
stabilize_any_of(list(1L, "a"), stabilize_int, stabilize_chr)
# Errors with a combined message when all functions fail
try(stabilize_any_of(list(1, TRUE, "23", "maybe"), stabilize_lgl, stabilize_int))
# to_any_of() uses prototypes instead of functions
to_any_of(1L, integer(), character())
to_any_of("a", integer(), character())
to_any_of("1", integer(), character())
try(to_any_of(list(), integer(), character()))
Ensure an object 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
object is NULL.
stabilize_arg_scalar() is optimized to check for length-1 vectors.
Usage
stabilize_arg(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_arg_scalar(
x,
...,
allow_null = TRUE,
allow_zero_length = TRUE,
allow_na = TRUE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
x_arg |
( |
call |
|
x_class |
( |
allow_zero_length |
( |
Value
x, or an error condition with classes <stbl-error>,
<stbl-condition>, <rlang_error>, <error>, <condition>, and a
specific class by failure mode:
-
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSEinstabilize_arg_scalar(). -
<stbl-error-non_scalar>for non-scalar vectors instabilize_arg_scalar().
See Also
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
wrapper <- function(this_arg, ...) {
stabilize_arg(this_arg, ...)
}
wrapper(1)
wrapper(NULL)
wrapper(NA)
try(wrapper(NULL, allow_null = FALSE))
try(wrapper(NA, allow_na = FALSE))
try(wrapper(1, min_size = 2))
try(wrapper(1:10, max_size = 5))
stabilize_arg_scalar("a")
stabilize_arg_scalar(1L)
try(stabilize_arg_scalar(1:10))
Coerce to character with additional checks
Description
Compared to to_chr(), stabilize_chr() checks more details, but is slower.
stabilise_chr(), stabilize_character(), and stabilise_character() are
synonyms of stabilize_chr().
Usage
stabilize_chr(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_character(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_chr(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_character(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_characters |
( |
max_characters |
( |
regex |
|
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a character vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-character>whenxcannot be coerced to character. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-n_characters-too_few>when elements have fewer characters thanmin_characters. -
<stbl-error-n_characters-too_many>when elements have more characters thanmax_characters. -
<stbl-error-regex_mismatch>whenregexchecks fail. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other character functions:
are_chr_ish(),
specify_chr(),
stabilize_chr_scalar(),
to(),
to_chr(),
to_chr_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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("hi", "hey"), min_characters = 3))
try(stabilize_chr(c("hi", "hey"), max_characters = 2))
try(stabilize_chr(c("hide", "find", "find", "hide"), regex = "hide"))
try(stabilize_chr(c("a", "b", "z"), allowed_values = c("a", "b", "c")))
Coerce to length-1 character with additional checks
Description
Checks whether a vector can be coerced to a length-1 character vector.
stabilize_chr_scalar() is optimized to check for length-1 character vectors
(compared to stabilize_chr() with max_size = 1). stabilise_chr_scalar,
stabilize_character_scalar(), and stabilise_character_scalar are synonyms
of stabilize_chr_scalar().
Usage
stabilize_chr_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_character_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_chr_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_character_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_characters = NULL,
max_characters = NULL,
regex = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
min_characters |
( |
max_characters |
( |
regex |
|
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 character vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-character>whenxcannot be coerced to character. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-n_characters-too_few>when the element has fewer characters thanmin_characters. -
<stbl-error-n_characters-too_many>when the element has more characters thanmax_characters. -
<stbl-error-regex_mismatch>whenregexchecks fail. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other character functions:
are_chr_ish(),
specify_chr(),
stabilize_chr(),
to(),
to_chr(),
to_chr_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_chr_scalar(TRUE)
try(stabilize_chr_scalar(c(TRUE, FALSE, TRUE)))
try(stabilize_chr_scalar(NULL))
stabilize_chr_scalar(NULL, allow_null = TRUE)
Coerce to date with additional checks
Description
Compared to to_date(), stabilize_date() checks more details, but is
slower. stabilise_date() is a synonym of
stabilize_date().
Usage
stabilize_date(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_date(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a base::Date vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-date>whenxcannot be coerced to date. -
<stbl-error-incompatible_values-date>when some values cannot be safely converted to date. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other date functions:
locale_datetime_formats(),
specify_date(),
stabilize_date_scalar(),
to_date(),
to_date_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_date(as.Date("2024-01-01"))
stabilize_date("2024-01-01")
stabilize_date(NULL)
try(stabilize_date(NULL, allow_null = FALSE))
try(stabilize_date(c(as.Date("2024-01-01"), NA), allow_na = FALSE))
stabilize_date(
"11/13/2018",
accepted_datetime_formats = locale_datetime_formats("en_US.UTF-8")
)
try(stabilize_date("2024-01-01", min_value = "2024-06-01"))
try(stabilize_date("2024-12-01", max_value = "2024-06-01"))
try(stabilize_date(
c("2024-01-01", "2024-01-02"),
allowed_values = "2024-01-01"
))
Coerce to length-1 date with additional checks
Description
Checks whether a vector can be coerced to a length-1 base::Date vector.
stabilize_date_scalar() is optimized to check for length-1 date vectors
(compared to stabilize_date() with max_size = 1). stabilise_date_scalar
is a synonym of stabilize_date_scalar().
Usage
stabilize_date_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_date_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::Date vector, or an error condition
with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-date>whenxcannot be coerced to date. -
<stbl-error-incompatible_values-date>when some values cannot be safely converted to date. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other date functions:
locale_datetime_formats(),
specify_date(),
stabilize_date(),
to_date(),
to_date_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_date_scalar(as.Date("2024-01-01"))
stabilize_date_scalar("2024-01-01")
try(stabilize_date_scalar(c("2024-01-01", "2024-01-02")))
try(stabilize_date_scalar(NULL))
stabilize_date_scalar(NULL, allow_null = TRUE)
Coerce to double with additional checks
Description
Compared to to_dbl(), stabilize_dbl() checks more details, but is slower.
stabilise_dbl(), stabilize_double(), and stabilise_double() are
synonyms of stabilize_dbl().
Usage
stabilize_dbl(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a double vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-double>whenxcannot be coerced to double. -
<stbl-error-incompatible_values-double>when some values cannot be safely converted to double. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_value,max_value,exclusive_min_value, orexclusive_max_value. -
<stbl-error-allowed_values>when values are not inallowed_values. -
<stbl-error-not_multiple>when values are not a multiple ofmultiple_of.
See Also
Other double functions:
are_dbl_ish(),
specify_dbl(),
stabilize_dbl_scalar(),
to(),
to_dbl(),
to_dbl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
try(stabilize_dbl(1:10, exclusive_min_value = 3))
try(stabilize_dbl(1:10, exclusive_max_value = 8))
try(stabilize_dbl(c(1.1, 2.2, 3.3), allowed_values = c(1.1, 2.2)))
try(stabilize_dbl(c(0.1, 0.25), multiple_of = 0.05))
Coerce to length-1 double with additional checks
Description
Checks whether a vector can be coerced to a length-1 double vector.
stabilize_dbl_scalar() is optimized to check for length-1 double vectors
(compared to stabilize_dbl() with max_size = 1). stabilise_dbl_scalar,
stabilize_double_scalar(), and stabilise_double_scalar are synonyms of
stabilize_dbl_scalar().
Usage
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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 double vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-double>whenxcannot be coerced to double. -
<stbl-error-incompatible_values-double>when some values cannot be safely converted to double. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_value,max_value,exclusive_min_value, orexclusive_max_value. -
<stbl-error-allowed_values>when the value is not inallowed_values. -
<stbl-error-not_multiple>when the value is not a multiple ofmultiple_of.
See Also
Other double functions:
are_dbl_ish(),
specify_dbl(),
stabilize_dbl(),
to(),
to_dbl(),
to_dbl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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 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,
.allow_zero_length = TRUE,
.required = ...names(),
.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,
.allow_zero_length = TRUE,
.required = ...names(),
.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,
.allow_zero_length = TRUE,
.required = ...names(),
.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,
.allow_zero_length = TRUE,
.required = ...names(),
.x_arg = caller_arg(.x),
.call = caller_env(),
.x_class = object_type(.x)
)
Arguments
.x |
The object to stabilize. |
... |
Named stabilizer functions, such as |
.extra_cols |
Controls how columns of
|
.col_names |
|
.min_rows |
( |
.max_rows |
( |
.allow_null |
( |
.allow_zero_length |
( |
.required |
|
.x_arg |
( |
.call |
|
.x_class |
( |
Value
The validated data frame, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-bad_null>forNULLvalues when.allow_null = FALSE. -
<stbl-error-coerce-data.frame>when.xcannot be coerced to a data frame. -
<stbl-error-jagged>when list input has incompatible element lengths for conversion to a data frame. -
<stbl-error-too_few_rows>when the data frame has fewer than.min_rowsrows. -
<stbl-error-too_many_rows>when the data frame has more than.max_rowsrows. -
<stbl-error-missing_cols>when required names in.col_namesare absent. -
<stbl-error-unnamed_spec>when any element passed through...is unnamed. -
<stbl-error-missing_element>,<stbl-error-bad_named>,<stbl-error-bad_unnamed>, or<stbl-error-duplicate_names>when list-like column checks delegated tostabilize_lst()fail.
See Also
Other data frame functions:
specify_df(),
to(),
to_df()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# Basic validation: required columns with type specs
stabilize_df(
data.frame(name = "Alice", age = 30L),
name = specify_chr_scalar(),
age = specify_int_scalar()
)
# Validate 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 = assert_present
)
# Allow extra columns unchecked with .extra_cols = TRUE
stabilize_df(
data.frame(name = "Alice", age = 30L, score = 99.5),
name = specify_chr_scalar(),
.extra_cols = TRUE
)
# Check required column names without validating contents
stabilize_df(
mtcars,
.col_names = c("mpg", "cyl"),
.extra_cols = assert_present
)
# Enforce row count constraints
try(
stabilize_df(mtcars[0, ], .min_rows = 1, .extra_cols = assert_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"))
# Mark a column as optional via .required
stabilize_df(
data.frame(name = "Alice"),
name = specify_chr_scalar(),
age = specify_int_scalar(),
.required = "name"
)
Coerce to date-time with additional checks
Description
Compared to to_dttm(), stabilize_dttm() checks more details, but is
slower. stabilise_dttm(), stabilize_datetime(), stabilise_dttm(),
stabilize_datetime(), and stabilise_datetime() are synonyms of
stabilize_dttm().
Usage
stabilize_dttm(
x,
...,
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_dttm(
x,
...,
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_datetime(
x,
...,
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_datetime(
x,
...,
tz = "UTC",
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a base::POSIXct vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-datetime>whenxcannot be coerced to datetime. -
<stbl-error-incompatible_values-datetime>when some values cannot be safely converted to datetime. -
<stbl-error-bad_tz>whentzis not""or a value fromOlsonNames(). -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other datetime functions:
locale_datetime_formats(),
specify_dttm(),
stabilize_dttm_scalar(),
to_dttm(),
to_dttm_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_dttm(as.POSIXct("2024-01-01 12:00:00", tz = "UTC"))
stabilize_dttm("2024-01-01T12:00:00Z")
stabilize_dttm(NULL)
try(stabilize_dttm(NULL, allow_null = FALSE))
try(stabilize_dttm(
c("2024-01-01T12:00:00Z", NA),
allow_na = FALSE
))
stabilize_dttm("2024-01-01 12:00:00")
try(stabilize_dttm(
"2024-01-01T12:00:00Z",
min_value = "2024-06-01T00:00:00Z"
))
try(stabilize_dttm(
"2024-12-01T00:00:00Z",
max_value = "2024-06-01T00:00:00Z"
))
Coerce to length-1 date-time with additional checks
Description
Checks whether a vector can be coerced to a length-1 base::POSIXct vector.
stabilize_dttm_scalar() is optimized to check for length-1 date-time
vectors (compared to stabilize_dttm() with max_size = 1).
stabilise_dttm_scalar are synonyms of stabilize_dttm_scalar().
Usage
stabilize_dttm_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_dttm_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_datetime_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_datetime_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
accepted_datetime_formats = locale_datetime_formats(),
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
accepted_datetime_formats |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::POSIXct vector, or an error
condition with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-datetime>whenxcannot be coerced to datetime. -
<stbl-error-incompatible_values-datetime>when some values cannot be safely converted to datetime. -
<stbl-error-bad_tz>whentzis not""or a value fromOlsonNames(). -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other datetime functions:
locale_datetime_formats(),
specify_dttm(),
stabilize_dttm(),
to_dttm(),
to_dttm_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_dttm_scalar(as.POSIXct("2024-01-01 12:00:00", tz = "UTC"))
stabilize_dttm_scalar("2024-01-01T12:00:00Z")
try(stabilize_dttm_scalar(c(
"2024-01-01T12:00:00Z",
"2024-01-02T12:00:00Z"
)))
try(stabilize_dttm_scalar(NULL))
stabilize_dttm_scalar(NULL, allow_null = TRUE)
Coerce to duration with additional checks
Description
Compared to to_dur(), stabilize_dur() checks more details, but is slower.
stabilise_dur(), stabilize_duration(), and stabilise_duration() are
synonyms of stabilize_dur().
Usage
stabilize_dur(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_dur(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_duration(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_duration(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Details
min_value, max_value, and allowed_values comparisons rely on
lubridate's approximate, nominal lengths for years and months (see
to_dur()); treat range checks on calendar-aware durations as approximate.
Value
The input as a lubridate::Period vector, or an error
condition with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-duration>whenxcannot be coerced to a duration. -
<stbl-error-incompatible_values-duration>when some values cannot be safely converted to a duration. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other duration functions:
specify_dur(),
stabilize_dur_scalar(),
to_dur(),
to_dur_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_dur(lubridate::period(day = 1))
stabilize_dur("P3Y6M4DT12H30M5S")
stabilize_dur(NULL)
try(stabilize_dur(NULL, allow_null = FALSE))
try(stabilize_dur(c("P1D", NA), allow_na = FALSE))
try(stabilize_dur("P"))
try(stabilize_dur("P1D", min_value = "P2D"))
try(stabilize_dur("P2D", max_value = "P1D"))
Coerce to length-1 duration with additional checks
Description
Checks whether a vector can be coerced to a length-1
lubridate::Period vector. stabilize_dur_scalar() is optimized to
check for length-1 duration vectors (compared to stabilize_dur() with
max_size = 1). stabilise_dur_scalar, stabilize_duration_scalar, and
stabilise_duration_scalar are synonyms of stabilize_dur_scalar().
Usage
stabilize_dur_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_dur_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilize_duration_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_duration_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 lubridate::Period vector, or an
error condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by failure
mode:
-
<stbl-error-coerce-duration>whenxcannot be coerced to a duration. -
<stbl-error-incompatible_values-duration>when some values cannot be safely converted to a duration. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other duration functions:
specify_dur(),
stabilize_dur(),
to_dur(),
to_dur_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_dur_scalar(lubridate::period(day = 1))
stabilize_dur_scalar("P1D")
try(stabilize_dur_scalar(c("P1D", "P2D")))
try(stabilize_dur_scalar(NULL))
stabilize_dur_scalar(NULL, allow_null = TRUE)
Ensure every element of x satisfies a single spec
Description
stabilize_each() applies spec (a to_* function, stabilize_*
function, or specify_*() result) to every element of x independently,
collecting every failing location before erroring, rather than stopping
at the first failure like to_each(). stabilise_each() is a synonym.
Usage
stabilize_each(
x,
spec,
...,
simplify = TRUE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_each(
x,
spec,
...,
simplify = TRUE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
spec |
|
... |
Arguments passed to methods. |
simplify |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
x with every element coerced by spec, simplified to an atomic
vector when simplify = TRUE and possible, otherwise a list. Errors with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and <stbl-error-cant_stabilize_each> when any element
fails spec; the condition's locations element gives the positions
that failed.
See Also
Other multiple type functions:
to_each()
Examples
stabilize_each(list("1", "2", "3"), stabilize_int)
stabilize_each(list(1L, 2L, 3L), stabilize_chr)
# Elements that can't be simplified into a common type stay a list
stabilize_each(list(1L, "a"), specify_any_of(specify_int(), specify_chr()))
# Reports every failing location, not just the first
try(stabilize_each(list("1", "a", "b"), stabilize_int))
Coerce to factor with additional checks
Description
Compared to to_fct(), stabilize_fct() checks more details, but is
slower. stabilise_fct(), stabilize_factor(), and stabilise_factor()
are synonyms of stabilize_fct().
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)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
levels |
|
to_na |
|
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a factor, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-factor>whenxcannot be coerced to factor. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-fct_levels>when values are not present inlevels.
See Also
Other factor functions:
are_fct_ish(),
specify_fct(),
stabilize_fct_scalar(),
to(),
to_fct(),
to_fct_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
Coerce to length-1 factor with additional checks
Description
Checks whether a vector can be coerced to a length-1 factor.
stabilize_fct_scalar() is optimized to check for length-1 factors
(compared to stabilize_fct() with max_size = 1). stabilise_fct_scalar,
stabilize_factor_scalar(), and stabilise_factor_scalar are synonyms of
stabilize_fct_scalar().
Usage
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)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
levels |
|
to_na |
|
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 factor, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-factor>whenxcannot be coerced to factor. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-fct_levels>when values are not present inlevels.
See Also
Other factor functions:
are_fct_ish(),
specify_fct(),
stabilize_fct(),
to(),
to_fct(),
to_fct_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_fct_scalar("a")
try(stabilize_fct_scalar(letters))
try(stabilize_fct_scalar("c", levels = c("a", "b")))
Coerce to integer with additional checks
Description
Compared to to_int(), stabilize_int() checks more details, but is slower.
stabilise_int(), stabilize_integer(), and stabilise_integer() are
synonyms of stabilize_int().
Usage
stabilize_int(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
coerce_character = TRUE,
coerce_factor = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
unique = FALSE,
min_value = NULL,
max_value = NULL,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as an integer vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-integer>whenxcannot be coerced to integer. -
<stbl-error-incompatible_values-integer>when some values cannot be safely converted to integer. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_value,max_value,exclusive_min_value, orexclusive_max_value. -
<stbl-error-allowed_values>when values are not inallowed_values. -
<stbl-error-not_multiple>when values are not a multiple ofmultiple_of.
See Also
Other integer functions:
are_int_ish(),
specify_int(),
stabilize_int_scalar(),
to(),
to_int(),
to_int_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
try(stabilize_int(1:10, exclusive_min_value = 3))
try(stabilize_int(1:10, exclusive_max_value = 8))
try(stabilize_int(1:5, allowed_values = c(1L, 2L, 3L)))
try(stabilize_int(1:5, multiple_of = 2))
Coerce to length-1 integer with additional checks
Description
Checks whether a vector can be coerced to a length-1 integer vector.
stabilize_int_scalar() is optimized to check for length-1 integer vectors
(compared to stabilize_int() with max_size = 1). stabilise_int_scalar,
stabilize_integer_scalar(), and stabilise_integer_scalar are synonyms of
stabilize_int_scalar().
Usage
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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = 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,
exclusive_min_value = NULL,
exclusive_max_value = NULL,
allowed_values = NULL,
multiple_of = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
coerce_character |
( |
coerce_factor |
( |
min_value |
( |
max_value |
( |
exclusive_min_value |
( |
exclusive_max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
multiple_of |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 integer vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-integer>whenxcannot be coerced to integer. -
<stbl-error-incompatible_values-integer>when some values cannot be safely converted to integer. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_value,max_value,exclusive_min_value, orexclusive_max_value. -
<stbl-error-allowed_values>when the value is not inallowed_values. -
<stbl-error-not_multiple>when the value is not a multiple ofmultiple_of.
See Also
Other integer functions:
are_int_ish(),
specify_int(),
stabilize_int(),
to(),
to_int(),
to_int_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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)
Coerce to logical with additional checks
Description
Compared to to_lgl(), stabilize_lgl() checks more details, but is
slower. stabilise_lgl(), stabilize_logical(), and stabilise_logical()
are synonyms of stabilize_lgl().
Usage
stabilize_lgl(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
allowed_values = 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,
allowed_values = 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,
allowed_values = 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,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a logical vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-logical>whenxcannot be coerced to logical. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other logical functions:
are_lgl_ish(),
specify_lgl(),
stabilize_lgl_scalar(),
to(),
to_lgl(),
to_lgl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
try(stabilize_lgl(c(TRUE, FALSE), allowed_values = TRUE))
Coerce to length-1 logical with additional checks
Description
Checks whether a vector can be coerced to a length-1 logical vector.
stabilize_lgl_scalar() is optimized to check for length-1 logical vectors
(compared to stabilize_lgl() with max_size = 1). stabilise_lgl_scalar,
stabilize_logical_scalar(), and stabilise_logical_scalar are synonyms of
stabilize_lgl_scalar().
Usage
stabilize_lgl_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
allowed_values = NULL,
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,
allowed_values = NULL,
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,
allowed_values = NULL,
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,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 logical vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-logical>whenxcannot be coerced to logical. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other logical functions:
are_lgl_ish(),
specify_lgl(),
stabilize_lgl(),
to(),
to_lgl(),
to_lgl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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 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,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names(),
.x_arg = caller_arg(.x),
.call = caller_env(),
.x_class = object_type(.x)
)
stabilize_list(
.x,
...,
.named = NULL,
.unnamed = NULL,
.allow_duplicate_names = FALSE,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names(),
.x_arg = caller_arg(.x),
.call = caller_env(),
.x_class = object_type(.x)
)
stabilise_lst(
.x,
...,
.named = NULL,
.unnamed = NULL,
.allow_duplicate_names = FALSE,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names(),
.x_arg = caller_arg(.x),
.call = caller_env(),
.x_class = object_type(.x)
)
stabilise_list(
.x,
...,
.named = NULL,
.unnamed = NULL,
.allow_duplicate_names = FALSE,
.unique = FALSE,
.allow_null = TRUE,
.allow_zero_length = TRUE,
.min_size = NULL,
.max_size = NULL,
.required = ...names(),
.x_arg = caller_arg(.x),
.call = caller_env(),
.x_class = object_type(.x)
)
Arguments
.x |
The object to stabilize. |
... |
Named stabilizer functions, such as |
.named |
Controls how named elements of
|
.unnamed |
Controls how unnamed elements of
|
.allow_duplicate_names |
( |
.unique |
( |
.allow_null |
( |
.allow_zero_length |
( |
.min_size |
( |
.max_size |
( |
.required |
|
.x_arg |
( |
.call |
|
.x_class |
( |
Value
The validated list, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-bad_null>forNULLvalues when.allow_null = FALSE. -
<stbl-error-coerce-list>when.xcannot be coerced to a list. -
<stbl-error-size_too_small>when the list is shorter than.min_size. -
<stbl-error-size_too_large>when the list is longer than.max_size. -
<stbl-error-duplicate_elements>when.unique = TRUEand duplicate elements are present. -
<stbl-error-unnamed_spec>when any element passed through...is unnamed. -
<stbl-error-missing_element>when a required named element is absent. -
<stbl-error-bad_unnamed>when unnamed elements are present but.unnamedisNULLorFALSE. -
<stbl-error-bad_named>when extra named elements are present but.namedisNULLorFALSE. -
<stbl-error-duplicate_names>when duplicate names are present and.allow_duplicate_names = FALSE.
See Also
Other list functions:
assert_present(),
specify_lst(),
to(),
to_lst()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# 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 assert_present
stabilize_lst(list(data = mtcars), data = assert_present)
# Validate extra named elements via .named
stabilize_lst(
list(a = 1L, b = 2L, c = 3L),
.named = specify_int_scalar()
)
# Allow extra named elements unchecked with .named = TRUE
stabilize_lst(list(a = 1L, b = "anything"), .named = TRUE)
# Validate unnamed elements via .unnamed
stabilize_lst(list(1L, 2L, 3L), .unnamed = specify_int_scalar())
# Allow unnamed elements unchecked with .unnamed = TRUE
stabilize_lst(list(1L, "anything"), .unnamed = TRUE)
# 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
)
# Mark named specs as optional via .required
stabilize_lst(
list(a = 1L),
a = specify_int_scalar(),
b = specify_int_scalar(),
.required = "a"
)
try(
stabilize_lst(list(a = 1L), a = specify_int_scalar(), b = specify_int_scalar())
)
Try to coerce or validate x as exactly one of several specifications
Description
stabilize_one_of() evaluates every function in ...
against x and requires that exactly one of them succeeds. It returns
the result of that single successful function. If zero functions
succeed, an informative error that combines the individual failure
messages is thrown; if two or more functions succeed, an error naming
the specifications that matched is thrown. stabilise_one_of() is a
synonym.
to_one_of() is analogous to to(): it tries to coerce x to each type
given in ... (as a prototype such as integer() or character()) and
requires that exactly one succeeds.
Usage
stabilize_one_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_one_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
to_one_of(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
For |
x_arg |
( |
call |
|
x_class |
( |
Value
x coerced or validated by the single successful function or
prototype in ..., or an error condition with classes <stbl-error>,
<stbl-condition>, <rlang_error>, <error>, <condition>, and a
specific class by failure mode:
-
<stbl-error-empty_specs>when no functions are supplied in.... -
<stbl-error-named_spec>when any element of...is named. -
<stbl-error-cant_stabilize_one_of>when zero, or more than one, provided functions succeed.
See Also
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
# Returns x unchanged when exactly one function succeeds
stabilize_one_of("a", stabilize_int, stabilize_chr)
# Coerces via the single matching function (1.5 can't become an integer)
stabilize_one_of(1.5, stabilize_int, stabilize_chr)
# Errors as ambiguous: "1" is both int-ish and dbl-ish
try(stabilize_one_of("1", stabilize_int, stabilize_dbl))
# Errors with a combined message when no function succeeds
try(stabilize_one_of(list(1, TRUE, "23", "maybe"), stabilize_lgl, stabilize_int))
# to_one_of() uses prototypes instead of functions
to_one_of("a", integer(), character())
# "FALSE" coerces to logical, but not to integer
to_one_of("FALSE", logical(), integer())
# Errors as ambiguous: "1" coerces to both integer and double
try(to_one_of("1", integer(), double()))
Deprecated: use assert_present() instead
Description
stabilize_present() was renamed to assert_present() because it doesn't
stabilize (coerce) x in any way; it only asserts that x is not NULL.
Calling stabilize_present() now throws an error directing you to
assert_present() instead.
Usage
stabilize_present(x, x_arg = caller_arg(x), call = caller_env())
Arguments
x |
The object to stabilize. |
x_arg |
( |
call |
|
Value
This function does not return a value; it always throws an error
condition with classes <stbl-error-deprecated>, <stbl-error>,
<stbl-condition>, <rlang_error>, <error>, and <condition>.
Coerce to time-of-day with additional checks
Description
Compared to to_time(), stabilize_time() checks more details, but is
slower. stabilise_time() is a synonym of stabilize_time().
Usage
stabilize_time(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_time(
x,
...,
allow_null = TRUE,
allow_na = TRUE,
min_size = NULL,
max_size = NULL,
unique = FALSE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_na |
( |
min_size |
( |
max_size |
( |
unique |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as an hms::hms() vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-time>whenxcannot be coerced to a time of day. -
<stbl-error-incompatible_values-time>when some values cannot be safely converted to a time of day. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-size_too_small>when the vector is shorter thanmin_size. -
<stbl-error-size_too_large>when the vector is longer thanmax_size. -
<stbl-error-duplicate_elements>whenunique = TRUEand duplicates are present. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when values are not inallowed_values.
See Also
Other time functions:
specify_time(),
stabilize_time_scalar(),
to_time(),
to_time_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_time(hms::hms(0, 20, 13))
stabilize_time("13:20:00Z")
stabilize_time(NULL)
try(stabilize_time(NULL, allow_null = FALSE))
try(stabilize_time(c("13:20:00Z", NA), allow_na = FALSE))
try(stabilize_time("13:20:00"))
try(stabilize_time("13:20:00Z", min_value = "18:00:00Z"))
try(stabilize_time("13:20:00Z", max_value = "06:00:00Z"))
Coerce to length-1 time-of-day with additional checks
Description
Checks whether a vector can be coerced to a length-1 hms::hms() vector.
stabilize_time_scalar() is optimized to check for length-1 time-of-day
vectors (compared to stabilize_time() with max_size = 1).
stabilise_time_scalar is a synonym of stabilize_time_scalar().
Usage
stabilize_time_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
stabilise_time_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
allow_na = TRUE,
min_value = NULL,
max_value = NULL,
allowed_values = NULL,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
allow_na |
( |
min_value |
( |
max_value |
( |
allowed_values |
A vector of permitted values (coerced to the target
type). |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 hms::hms() vector, or an error condition
with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-time>whenxcannot be coerced to a time of day. -
<stbl-error-incompatible_values-time>when some values cannot be safely converted to a time of day. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors. -
<stbl-error-bad_na>forNAvalues whenallow_na = FALSE. -
<stbl-error-outside_range>when values fall outsidemin_valueormax_value. -
<stbl-error-allowed_values>when the value is not inallowed_values.
See Also
Other time functions:
specify_time(),
stabilize_time(),
to_time(),
to_time_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
stabilize_time_scalar(hms::hms(0, 20, 13))
stabilize_time_scalar("13:20:00Z")
try(stabilize_time_scalar(c("13:20:00Z", "14:20:00Z")))
try(stabilize_time_scalar(NULL))
stabilize_time_scalar(NULL, allow_null = TRUE)
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
x |
The object to stabilize. |
.to |
A prototype that determines the target type (e.g., |
... |
Arguments passed to methods and on to |
x_arg |
( |
call |
|
x_class |
( |
levels |
|
Value
x coerced to the type of .to, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
The failure classes documented for the
to_*()function corresponding to the class of.to(for exampleto_int()for.to = integer()).-
<stbl-error-coerce-*>when the class of.tohas no correspondingto_*()function.
See Also
Other character functions:
are_chr_ish(),
specify_chr(),
stabilize_chr(),
stabilize_chr_scalar(),
to_chr(),
to_chr_scalar()
Other double functions:
are_dbl_ish(),
specify_dbl(),
stabilize_dbl(),
stabilize_dbl_scalar(),
to_dbl(),
to_dbl_scalar()
Other integer functions:
are_int_ish(),
specify_int(),
stabilize_int(),
stabilize_int_scalar(),
to_int(),
to_int_scalar()
Other logical functions:
are_lgl_ish(),
specify_lgl(),
stabilize_lgl(),
stabilize_lgl_scalar(),
to_lgl(),
to_lgl_scalar()
Other factor functions:
are_fct_ish(),
specify_fct(),
stabilize_fct(),
stabilize_fct_scalar(),
to_fct(),
to_fct_scalar()
Other function functions:
are_fn_ish(),
to_fn()
Other list functions:
assert_present(),
specify_lst(),
stabilize_lst(),
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)
Coerce to character
Description
Checks whether a vector 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().
Usage
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)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
Details
This function has two important differences from
base::as.character():
-
lists anddata.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:3". In the unlikely event that this is the expected behavior, useas.character()instead. -
NULLvalues can be rejected as part of the call to this function (withallow_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 input as a character vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-character>whenxcannot be coerced to character (for example adata.frame, or an anonymous function). -
<stbl-error-incompatible_values-character>when some elements of a list cannot be converted to character. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other character functions:
are_chr_ish(),
specify_chr(),
stabilize_chr(),
stabilize_chr_scalar(),
to(),
to_chr_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
Coerce to length-1 character
Description
Checks whether a vector can be coerced to a length-1 character vector.
to_character_scalar() is a synonym of to_chr_scalar().
Usage
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 character vector, or an error condition
with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-character>whenxcannot be coerced to character (for example adata.frame, or an anonymous function). -
<stbl-error-incompatible_values-character>when some elements of a list cannot be converted to character. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other character functions:
are_chr_ish(),
specify_chr(),
stabilize_chr(),
stabilize_chr_scalar(),
to(),
to_chr()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_chr_scalar("a")
try(to_chr_scalar(letters))
Coerce to date
Description
Checks whether a vector can be coerced to a base::Date without losing information, returning it silently if so. Otherwise an informative error message is signaled.
Usage
to_date(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class ''NULL''
to_date(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())
## S3 method for class 'character'
to_date(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'factor'
to_date(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'POSIXct'
to_date(x, ...)
## S3 method for class 'POSIXlt'
to_date(x, ...)
## S3 method for class 'numeric'
to_date(x, ...)
## S3 method for class 'integer'
to_date(x, ...)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Details
Character vectors must use the RFC 3339 full-date format
("YYYY-MM-DD"); any other shape (such as "11/13/2018") is rejected (but
see stabilize_date()). POSIXct and POSIXlt values are truncated to
their date component, discarding the time-of-day and timezone offset. Numeric
and integer values are treated as the number of days since the Unix epoch
("1970-01-01").
Value
The input as a base::Date vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-incompatible_values-date>when some values cannot be safely converted to date. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other date functions:
locale_datetime_formats(),
specify_date(),
stabilize_date(),
stabilize_date_scalar(),
to_date_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_date(as.Date("2024-01-01"))
to_date("2024-01-01")
to_date(c("2024-01-01", NA))
to_date(0L)
to_date(as.POSIXct("2024-01-01 23:00:00", tz = "UTC"))
to_date(NULL)
try(to_date("11/13/2018"))
try(to_date(c("2024-01-01", "not-a-date")))
Coerce to length-1 date
Description
Checks whether a vector can be coerced to a length-1 base::Date vector.
Usage
to_date_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::Date vector, or an error
condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-date>when some values cannot be safely converted to date. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other date functions:
locale_datetime_formats(),
specify_date(),
stabilize_date(),
stabilize_date_scalar(),
to_date()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_date_scalar("2024-01-01")
try(to_date_scalar(c("2024-01-01", "2024-01-02")))
Coerce to double
Description
Checks whether a vector 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().
Usage
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)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
coerce_character |
( |
coerce_factor |
( |
Value
The input as a double vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-double>whenxcannot be coerced to double. -
<stbl-error-incompatible_values-double>when some values cannot be safely converted to double. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other double functions:
are_dbl_ish(),
specify_dbl(),
stabilize_dbl(),
stabilize_dbl_scalar(),
to(),
to_dbl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
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))
Coerce to length-1 double
Description
Checks whether a vector can be coerced to a length-1 double vector.
to_double_scalar() is a synonym of to_dbl_scalar().
Usage
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 double vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-double>whenxcannot be coerced to double. -
<stbl-error-incompatible_values-double>when some values cannot be safely converted to double. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other double functions:
are_dbl_ish(),
specify_dbl(),
stabilize_dbl(),
stabilize_dbl_scalar(),
to(),
to_dbl()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_dbl_scalar("1.1")
try(to_dbl_scalar(1:10))
Ensure a data frame meets expectations
Description
to_df() checks whether an object 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
x |
The object to stabilize. |
... |
Arguments passed to |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Value
The object as a data frame, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-data.frame>whenxcannot be coerced to a data frame. -
<stbl-error-bad_named>when a list has any unnamed elements. -
<stbl-error-jagged>when a list has incompatible element lengths. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
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 date-time
Description
Checks whether a vector can be coerced to a base::POSIXct without losing
information, returning it silently if so. Otherwise an informative error
message is signaled. to_datetime() is a synonym of to_dttm().
Usage
to_dttm(
x,
...,
tz = "UTC",
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
to_datetime(
x,
...,
tz = "UTC",
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'POSIXct'
to_dttm(x, ..., tz = "UTC", call = caller_env())
## S3 method for class ''NULL''
to_dttm(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())
## S3 method for class 'character'
to_dttm(
x,
...,
tz = "UTC",
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'factor'
to_dttm(
x,
...,
tz = "UTC",
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'POSIXlt'
to_dttm(x, ..., tz = "UTC", call = caller_env())
## S3 method for class 'Date'
to_dttm(x, ..., tz = "UTC", call = caller_env())
## S3 method for class 'numeric'
to_dttm(x, ..., tz = "UTC", call = caller_env())
## S3 method for class 'integer'
to_dttm(x, ..., tz = "UTC", call = caller_env())
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Details
Character vectors must use the RFC 3339 date-time format
("YYYY-MM-DDTHH:MM:SS", optionally followed by fractional seconds and
either "Z" or a numeric offset such as "+05:00"); any other shape is
rejected (but see stabilize_dttm()). A space may be used instead of "T"
to separate the date and time. All values are normalized to the time zone
named by tz ("UTC" by default); the underlying instant in time is
preserved, only its display time zone changes. Numeric and integer values are
treated as the number of seconds since the Unix epoch ("1970-01-01 00:00:00 UTC"). base::Date values are treated as midnight UTC on that date.
Value
The input as a base::POSIXct vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-incompatible_values-datetime>when some values cannot be safely converted to datetime. -
<stbl-error-bad_tz>whentzis not""or a value fromOlsonNames(). -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other datetime functions:
locale_datetime_formats(),
specify_dttm(),
stabilize_dttm(),
stabilize_dttm_scalar(),
to_dttm_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_dttm(as.POSIXct("2024-01-01 12:00:00", tz = "UTC"))
to_dttm("2024-01-01T12:00:00Z")
to_dttm("2024-01-01T12:00:00-05:00")
to_dttm(c("2024-01-01T12:00:00Z", NA))
to_dttm(0L)
to_dttm(as.Date("2024-01-01"))
to_dttm(NULL)
try(to_dttm("2024-01-01 12:00:00"))
try(to_dttm(c("2024-01-01T12:00:00Z", "not-a-datetime")))
Coerce to length-1 date-time
Description
Checks whether a vector can be coerced to a length-1 base::POSIXct vector.
to_datetime_scalar() is a synonym of to_dttm_scalar().
Usage
to_dttm_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
to_datetime_scalar(
x,
...,
tz = "UTC",
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
tz |
( |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 base::POSIXct vector, or an error
condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-datetime>when some values cannot be safely converted to datetime. -
<stbl-error-bad_tz>whentzis not""or a value fromOlsonNames(). -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other datetime functions:
locale_datetime_formats(),
specify_dttm(),
stabilize_dttm(),
stabilize_dttm_scalar(),
to_dttm()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_dttm_scalar("2024-01-01T12:00:00Z")
try(to_dttm_scalar(c(
"2024-01-01T12:00:00Z",
"2024-01-02T12:00:00Z"
)))
Coerce to a duration
Description
Checks whether a vector can be coerced to a lubridate::Period without losing information, returning it silently if so. Otherwise an informative error message is signaled.
Usage
to_dur(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
to_duration(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class ''NULL''
to_dur(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())
## S3 method for class 'Period'
to_dur(x, ...)
## S3 method for class 'character'
to_dur(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'factor'
to_dur(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'difftime'
to_dur(x, ..., call = caller_env())
## S3 method for class 'numeric'
to_dur(x, ..., call = caller_env())
## S3 method for class 'integer'
to_dur(x, ..., call = caller_env())
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Details
Period is chosen as the target class because it preserves the calendar
components (years, months, days, hours, minutes, seconds) of an RFC 3339 / ISO 8601 duration string separately,
rather than collapsing them into a single number of seconds. That fidelity
comes at a cost: years and months have no fixed length, so comparisons
(min_value, max_value, allowed_values in stabilize_dur()) use
lubridate's approximate, nominal lengths (a 365.25-day year, a 30.4375-day
month) and may not reflect the actual elapsed time implied by a specific
calendar date.
Character vectors must use the RFC 3339 duration format: "P"
followed by an optional number of years (Y), months (M), and days (D),
then an optional "T"-prefixed block of hours (H), minutes (M), and
seconds (S) (for example "P3Y6M4DT12H30M5S", "P23DT23H", or "PT1M");
or a stand-alone week form ("P4W"). The date/time form and the week form
cannot be mixed, fractional components are not permitted, and "P" or "PT"
alone (with no components) are not valid durations. base::difftime values
(including hms::hms()) are converted directly, preserving their unit.
Numeric and integer values are treated as a (fractional) number of seconds
and broken into day/hour/minute/second components, with no year or month
component, since a number of seconds cannot unambiguously imply a calendar
length.
to_dur() requires the lubridate package.
Value
The input as a lubridate::Period vector, or an error
condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-duration>when some values cannot be safely converted to a duration. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other duration functions:
specify_dur(),
stabilize_dur(),
stabilize_dur_scalar(),
to_dur_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_dur(lubridate::period(year = 1, month = 2, day = 3))
to_dur("P3Y6M4DT12H30M5S")
to_dur("PT1M")
to_dur("P4W")
to_dur(c("P1D", NA))
to_dur(3661)
to_dur(as.difftime(90, units = "mins"))
to_dur(NULL)
try(to_dur("P"))
try(to_dur(c("P1D", "not-a-duration")))
Coerce to length-1 duration
Description
Checks whether a vector can be coerced to a length-1 lubridate::Period vector.
Usage
to_dur_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 lubridate::Period vector, or an
error condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-duration>when some values cannot be safely converted to a duration. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other duration functions:
specify_dur(),
stabilize_dur(),
stabilize_dur_scalar(),
to_dur()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_dur_scalar("P1D")
try(to_dur_scalar(c("P1D", "P2D")))
Coerce each element of x with a single spec
Description
to_each() applies spec (a to_* function, stabilize_* function, or
specify_*() result) to every element of x, and stops at the first
element that fails.
Usage
to_each(
x,
spec,
...,
simplify = TRUE,
x_arg = caller_arg(x),
call = caller_env()
)
Arguments
x |
The object to stabilize. |
spec |
|
... |
Arguments passed to methods. |
simplify |
( |
x_arg |
( |
call |
|
Value
x with every element coerced by spec, simplified to an atomic
vector when simplify = TRUE and possible, otherwise a list. Errors with
whatever condition spec throws for the first failing element.
See Also
Other multiple type functions:
stabilize_each()
Examples
to_each(list("1", "2", "3"), to_int)
to_each(list(1L, 2L, 3L), to_chr)
# Elements that can't be simplified into a common type stay a list
to_each(list(1L, "a"), specify_any_of(specify_int(), specify_chr()))
# Stops at the first element that fails
try(to_each(list("1", "a"), to_int))
Coerce to factor
Description
Checks whether a vector 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().
Usage
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())
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
levels |
|
to_na |
|
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Details
This function has important differences from base::as.factor()
and base::factor():
Values are never silently coerced to
NAunless they are explicitly supplied in theto_naargument.-
NULLvalues can be rejected as part of the call to this function (withallow_null = FALSE).
Value
The input as a factor, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-factor>whenxcannot be coerced to factor. -
<stbl-error-incompatible_values-factor>when some elements of a list cannot be converted to factor. -
<stbl-error-fct_levels>when values are not present inlevels. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other factor functions:
are_fct_ish(),
specify_fct(),
stabilize_fct(),
stabilize_fct_scalar(),
to(),
to_fct_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_fct("a")
to_fct(1:10)
to_fct(NULL)
try(to_fct(letters[1:5], levels = c("a", "c"), to_na = "b"))
Coerce to length-1 factor
Description
Checks whether a vector can be coerced to a length-1 factor.
to_fct_scalar() is optimized to check for length-1 factors (compared to
stabilize_fct() with max_size = 1). to_factor_scalar() is a synonym
of to_fct_scalar().
Usage
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
levels |
|
to_na |
|
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 factor, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-factor>whenxcannot be coerced to factor. -
<stbl-error-incompatible_values-factor>when some elements of a list cannot be converted to factor. -
<stbl-error-fct_levels>when values are not present inlevels. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other factor functions:
are_fct_ish(),
specify_fct(),
stabilize_fct(),
stabilize_fct_scalar(),
to(),
to_fct()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_fct_scalar("a")
try(to_fct_scalar(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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
definition_env |
|
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, or an error condition with classes <stbl-error>,
<stbl-condition>, <rlang_error>, <error>, <condition>, and a
specific class by failure mode:
-
<stbl-error-coerce-function>whenxcannot be coerced to a function. -
<stbl-error-invalid_function_name>whenxis not a syntactically valid function name. -
<stbl-error-unknown_function>whenxis a syntactically valid name that doesn't resolve to a known function. -
<stbl-error-non_scalar>whenxhas more than one element. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
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)
Coerce to integer
Description
Checks whether a vector 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().
Usage
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)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
coerce_character |
( |
coerce_factor |
( |
Value
The input as an integer vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-integer>whenxcannot be coerced to integer. -
<stbl-error-incompatible_values-integer>when some values cannot be safely converted to integer. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other integer functions:
are_int_ish(),
specify_int(),
stabilize_int(),
stabilize_int_scalar(),
to(),
to_int_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
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")))
Coerce to length-1 integer
Description
Checks whether a vector can be coerced to a length-1 integer vector.
to_integer_scalar() is a synonym of to_int_scalar().
Usage
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 integer vector, or an error condition with
classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-integer>whenxcannot be coerced to integer. -
<stbl-error-incompatible_values-integer>when some values cannot be safely converted to integer. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other integer functions:
are_int_ish(),
specify_int(),
stabilize_int(),
stabilize_int_scalar(),
to(),
to_int()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_lgl(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
Examples
to_int_scalar("1")
try(to_int_scalar(1:10))
Coerce to logical
Description
Checks whether a vector 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().
Usage
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())
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Value
The input as a logical vector, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-logical>whenxcannot be coerced to logical. -
<stbl-error-incompatible_values-logical>when some values cannot be safely converted to logical. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other logical functions:
are_lgl_ish(),
specify_lgl(),
stabilize_lgl(),
stabilize_lgl_scalar(),
to(),
to_lgl_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl_scalar(),
to_time(),
to_time_scalar()
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)))
Coerce to length-1 logical
Description
Checks whether a vector can be coerced to a length-1 logical vector.
to_logical_scalar() is a synonym of to_lgl_scalar().
Usage
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
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 logical vector, or an error condition
with classes <stbl-error>, <stbl-condition>, <rlang_error>,
<error>, <condition>, and a specific class by failure mode:
-
<stbl-error-coerce-logical>whenxcannot be coerced to logical. -
<stbl-error-incompatible_values-logical>when some values cannot be safely converted to logical. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other logical functions:
are_lgl_ish(),
specify_lgl(),
stabilize_lgl(),
stabilize_lgl_scalar(),
to(),
to_lgl()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_time(),
to_time_scalar()
Examples
to_lgl_scalar("TRUE")
try(to_lgl_scalar(c(TRUE, FALSE)))
Ensure a list meets expectations
Description
to_lst() checks whether an object 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
x |
The object to stabilize. |
... |
Arguments passed to |
x_arg |
( |
call |
|
allow_null |
( |
coerce_function |
( |
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 withbase::as.list().Primitive functions (such as
base::is.na()orbase::is.list()) always throw an error, rather than returninglist(NULL).-
NULLvalues can be rejected as part of the call to this function (withallow_null = FALSE).
Value
The object as a list, or an error condition with classes
<stbl-error>, <stbl-condition>, <rlang_error>, <error>,
<condition>, and a specific class by failure mode:
-
<stbl-error-coerce-list>whenxis a primitive function. -
<stbl-error-bad_function>for functions whencoerce_function = FALSE(the default). -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other list functions:
assert_present(),
specify_lst(),
stabilize_lst(),
to()
Coerce to time-of-day
Description
Checks whether a vector can be coerced to an hms::hms() time-of-day vector
without losing information, returning it silently if so. Otherwise an
informative error message is signaled.
Usage
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class ''NULL''
to_time(x, ..., allow_null = TRUE, x_arg = caller_arg(x), call = caller_env())
## S3 method for class 'character'
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'factor'
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'POSIXct'
to_time(x, ..., call = caller_env())
## S3 method for class 'POSIXlt'
to_time(x, ..., call = caller_env())
## S3 method for class 'numeric'
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'integer'
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
## S3 method for class 'difftime'
to_time(
x,
...,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
x_arg |
( |
call |
|
x_class |
( |
allow_null |
( |
Details
Character vectors must use the RFC 3339 full-time format
("HH:MM:SS", optionally followed by fractional seconds and a mandatory
offset of either "Z" or a numeric offset such as "+05:00"); any other
shape is rejected. The offset is used only to normalize the value to UTC and
is not retained: to_time() always returns the time-of-day expressed in UTC.
base::POSIXct and base::POSIXlt values are likewise converted to UTC
before their time-of-day component is extracted. Numeric and base::difftime
values are treated as (fractional) seconds since midnight and must resolve to
a value in [0, 86400).
to_time() requires the hms package.
Value
The input as an hms::hms() vector, always expressed in UTC, or
an error condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-time>when some values cannot be safely converted to a time of day. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE.
See Also
Other time functions:
specify_time(),
stabilize_time(),
stabilize_time_scalar(),
to_time_scalar()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time_scalar()
Examples
to_time(hms::hms(0, 20, 13))
to_time("13:20:00Z")
to_time("13:20:00-05:00")
to_time(c("13:20:00Z", NA))
to_time(3600)
to_time(as.POSIXct("2024-01-01 13:20:00", tz = "UTC"))
to_time(NULL)
try(to_time("13:20:00"))
try(to_time(c("13:20:00Z", "not-a-time")))
Coerce to length-1 time-of-day
Description
Checks whether a vector can be coerced to a length-1 hms::hms() vector.
Usage
to_time_scalar(
x,
...,
allow_null = FALSE,
allow_zero_length = FALSE,
x_arg = caller_arg(x),
call = caller_env(),
x_class = object_type(x)
)
Arguments
x |
The object to stabilize. |
... |
Arguments passed to methods. |
allow_null |
( |
allow_zero_length |
( |
x_arg |
( |
call |
|
x_class |
( |
Value
The input as a length-1 hms::hms() vector, or an error
condition with classes <stbl-error>, <stbl-condition>,
<rlang_error>, <error>, <condition>, and a specific class by
failure mode:
-
<stbl-error-incompatible_values-time>when some values cannot be safely converted to a time of day. -
<stbl-error-bad_null>forNULLvalues whenallow_null = FALSE. -
<stbl-error-bad_empty>for empty vectors whenallow_zero_length = FALSE. -
<stbl-error-non_scalar>for non-scalar vectors.
See Also
Other time functions:
specify_time(),
stabilize_time(),
stabilize_time_scalar(),
to_time()
Other stabilization functions:
assert_contains(),
assert_not(),
assert_present(),
stabilize_all_of(),
stabilize_any_of(),
stabilize_arg(),
stabilize_chr(),
stabilize_chr_scalar(),
stabilize_date(),
stabilize_date_scalar(),
stabilize_dbl(),
stabilize_dbl_scalar(),
stabilize_df(),
stabilize_dttm(),
stabilize_dttm_scalar(),
stabilize_dur(),
stabilize_dur_scalar(),
stabilize_fct(),
stabilize_fct_scalar(),
stabilize_int(),
stabilize_int_scalar(),
stabilize_lgl(),
stabilize_lgl_scalar(),
stabilize_lst(),
stabilize_one_of(),
stabilize_time(),
stabilize_time_scalar(),
to_chr(),
to_chr_scalar(),
to_date(),
to_date_scalar(),
to_dbl(),
to_dbl_scalar(),
to_dttm(),
to_dttm_scalar(),
to_dur(),
to_dur_scalar(),
to_fct(),
to_fct_scalar(),
to_int(),
to_int_scalar(),
to_lgl(),
to_lgl_scalar(),
to_time()
Examples
to_time_scalar("13:20:00Z")
try(to_time_scalar(c("13:20:00Z", "14:20:00Z")))