R is flexible about classes. Variables are not declared with explicit classes, and arguments of the “wrong” class don’t cause errors until they explicitly fail at some point in the call stack. It would be helpful to keep that flexibility from a user standpoint, but to error informatively and quickly if the inputs will not work for a computation. The purpose of stbl is to allow programmers to specify what they want, and to then see if what the user supplied can work for that purpose.
This approach aligns with Postel’s Law:
“Be conservative in what you send. Be liberal in what you accept from others.”
stbl is liberal about what it accepts (by coercing when safe) and conservative about what it returns (by ensuring that inputs have the classes and other features that are expected).
Install the released version of stbl from CRAN:
install.packages("stbl")
Install the development version of stbl from GitHub:
# install.packages("pak")
::pak("api2r/stbl") pak
The primary use-case for stbl is to stabilize function arguments. The goal is to make sure arguments will work the way you expect them to work, and to give meaningful error messages when they won’t.
For example, perhaps you would like to protect against the case where data is not properly translated from character to integer when it’s loaded by a user.
Without the argument-stabilizers provided in stbl, error messages can be cryptic, and errors trigger when you might not want them to.
<- function(my_arg_name) {
my_old_fun + 1
my_arg_name
}my_old_fun("1")
#> Error in my_arg_name + 1: non-numeric argument to binary operator
stbl helps to ensure that arguments are what you expect them to be.
<- function(my_arg_name) {
my_fun <- stbl::to_int(my_arg_name)
my_arg_name + 1
my_arg_name
}my_fun("1")
#> [1] 2
Failures are reported with helpful messages.
my_fun("1.1")
#> Error in `my_fun()`:
#> ! `my_arg_name` <character> must be coercible to <integer>
#> ✖ Can't convert some values due to loss of precision.
#> • Locations: 1
The errors help locate issues within vectors.
my_fun(c("1", "2", "3.1", "4", "5.2"))
#> Error in `my_fun()`:
#> ! `my_arg_name` <character> must be coercible to <integer>
#> ✖ Can't convert some values due to loss of precision.
#> • Locations: 3 and 5
See vignette("stbl")
to learn more about how to use
stbl, and when to “upgrade” from to_*()
functions to
stabilize_*()
functions.
Other packages perform functions similar to stbl, but with different approaches:
to_*()
and
stabilize_*()
functions are similar to the
assert*ish()
functions from {checkmate} with
coerce = TRUE
. stbl is usually faster, and provided classed
error messages to allow you to handle different failure modes
differently.Please note that the stbl project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.