Movatterモバイル変換

stbl

R is flexible about classes. Variables are not declared with explicitclasses, and arguments of the “wrong” class don’t cause errors untilthey explicitly fail at some point in the call stack. It would behelpful to keep that flexibility from a user standpoint, but to errorinformatively 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 withPostel’sLaw:

“Be conservative in what you send. Be liberal in what you accept fromothers.”

stbl is liberal about what it accepts (by coercing when safe) andconservative about what it returns (by ensuring that inputs have theclasses and other features that are expected).

Installation

Install the released version of stbl fromCRAN:

install.packages("stbl")

# install.packages("pak")pak::pak("api2r/stbl")

Usage

The primary use-case for stbl is to stabilize function arguments. Thegoal is to make sure arguments will work the way you expect them towork, and to give meaningful error messages when they won’t.

For example, perhaps you would like to protect against the case wheredata is not properly translated from character to integer when it’sloaded by a user.

Without stbl:

Without the argument-stabilizers provided in stbl, error messages canbe cryptic, and errors trigger when you might not want them to.

my_old_fun<-function(my_arg_name) {  my_arg_name+1}my_old_fun("1")#> Error in my_arg_name + 1: non-numeric argument to binary operator

With stbl:

stbl helps to ensure that arguments are what you expect them tobe.

my_fun<-function(my_arg_name) {  my_arg_name<- stbl::to_int(my_arg_name)  my_arg_name+1}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

Seevignette("stbl") to learn more about how to usestbl, and when to “upgrade” fromto_*() functions tostabilize_*() functions.

Similar Packages

Other packages perform functions similar to stbl, but with differentapproaches:

• {checkmate}and related assertion packages: stbl’sto_*() andstabilize_*() functions are similar to theassert*ish() functions from {checkmate} withcoerce = TRUE. stbl is usually faster, and provided classederror messages to allow you to handle different failure modesdifferently.
• {vctrs}:{vctrs} provides strict, low-level tools for coercion and typeconsistency, especially useful in package internals and base-typeenforcement. stbl is more tolerant and higher-level, optimized for usein functions that accept flexible user inputs (e.g. letting a versionnumber 1.1 be passed in as numeric or character and handling bothgracefully).

Code of Conduct

Please note that the stbl project is released with aContributor Code ofConduct. By contributing to this project, you agree to abide by itsterms.