Skip to contents

Try to coerce or validate x as one of several types

Source: R/stabilize_any_of.R, R/to_any_of.R
stabilize_any_of.Rd

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 stabilize_any_of(): unnamed stabilizer or coercion functions, such as stabilize_* functions (stabilize_chr(), etc.), to_* functions (to_chr(), etc.), or functions produced by specify_*() calls (specify_chr(), etc.). For to_any_of(): prototype objects (e.g. integer(), character()) that determine the target types to try, passed as the .to argument of to().

x_arg

(character(1)) The name of the object being stabilized to use in error messages. The automatic value will work in most cases, or pass it through from higher-level functions to make error messages clearer in unexported functions.

call

(environment) The execution environment to mention as the source of error messages.

x_class

(character(1)) The class name of the object being stabilized to use in error messages. Use this if you remove a special class from the object before checking its coercion, but want the error message to match the original 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_present(), 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 the first function succeeds
stabilize_any_of(1L, stabilize_int, stabilize_chr)
#> [1] 1

# Falls through to stabilize_chr when stabilize_int fails
stabilize_any_of("a", stabilize_int, stabilize_chr)
#> [1] "a"

# Coerces via the first matching function ("1" -> 1L)
stabilize_any_of("1", stabilize_int, stabilize_chr)
#> [1] 1

# A mixed list falls through to stabilize_chr because "a" can't be integer
stabilize_any_of(list(1L, "a"), stabilize_int, stabilize_chr)
#> [1] "1" "a"

# Errors with a combined message when all functions fail
try(stabilize_any_of(list(1, TRUE, "23", "maybe"), stabilize_lgl, stabilize_int))
#> Error in eval(expr, envir) : 
#>   `list(1, TRUE, "23", "maybe")` must match at least one of the provided
#> stabilizers.
#> ✖ `list(1, TRUE, "23", "maybe")` <list> must be coercible to <logical>
#>   (Locations: 4)
#> ✖ `list(1, TRUE, "23", "maybe")` <list> must be coercible to <integer>
#>   (Locations: 4)
# to_any_of() uses prototypes instead of functions
to_any_of(1L, integer(), character())
#> [1] 1
to_any_of("a", integer(), character())
#> [1] "a"
to_any_of("1", integer(), character())
#> [1] 1
try(to_any_of(list(), integer(), character()))
#> integer(0)