Try to coerce or validate x as exactly one of several specifications

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 stabilize_one_of(): unnamed stabilizer or coercion functions, such as stabilize_* functions (stabilize_chr(), etc.), to_* functions (to_chr(), etc.), functions produced by specify_*() calls (specify_chr(), etc.), or assert_*() functions (such as assert_not()) that return their input unchanged. For to_one_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 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)
#> [1] "a"

# Coerces via the single matching function (1.5 can't become an integer)
stabilize_one_of(1.5, stabilize_int, stabilize_chr)
#> [1] "1.5"

# Errors as ambiguous: "1" is both int-ish and dbl-ish
try(stabilize_one_of("1", stabilize_int, stabilize_dbl))
#> Error in eval(expr, envir) : 
#>   `"1"` must match exactly one of the provided specifications, but matched
#> 2.
#> ℹ Matched specifications: "stabilize_int" and "stabilize_dbl"

# Errors with a combined message when no function succeeds
try(stabilize_one_of(list(1, TRUE, "23", "maybe"), stabilize_lgl, stabilize_int))
#> Error in eval(expr, envir) : 
#>   `list(1, TRUE, "23", "maybe")` must match exactly one of the provided
#> specifications, but matched none.
#> ✖ `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_one_of() uses prototypes instead of functions
to_one_of("a", integer(), character())
#> [1] "a"

# "FALSE" coerces to logical, but not to integer
to_one_of("FALSE", logical(), integer())
#> [1] FALSE

# Errors as ambiguous: "1" coerces to both integer and double
try(to_one_of("1", integer(), double()))
#> Error in eval(expr, envir) : 
#>   `"1"` must match exactly one of the provided specifications, but matched
#> 2.
#> ℹ Matched specifications: "integer" and "double"