Skip to contents

Coerce to integer with additional checks

Source: R/stabilize_int.R
stabilize_int.Rd

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,
  allowed_values = 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,
  allowed_values = 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,
  allowed_values = 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,
  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

(logical(1)) Is NULL an acceptable value?

allow_na

(logical(1)) Are NA values ok?

coerce_character

(logical(1)) Should character vectors such as "1" and "2.0" be considered numeric-ish?

coerce_factor

(logical(1)) Should factors with values such as "1" and "2.0" be considered numeric-ish? Note that this package uses the character value from the factor, while as.integer() and as.double() use the integer index of the factor.

min_size

(integer(1)) The minimum size of the object. Object size will be tested using vctrs::vec_size().

max_size

(integer(1)) The maximum size of the object. Object size will be tested using vctrs::vec_size().

unique

(logical(1)) Should all elements in x be distinct?

min_value

(numeric(1)) The lowest allowed value for x. If NULL (default) values are not checked.

max_value

(numeric(1)) The highest allowed value for x. If NULL (default) values are not checked.

allowed_values

A vector of permitted values (coerced to the target type). NULL (default) skips the check. NA values in x are permitted independently of allowed_values, subject to allow_na.

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

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> when x cannot be coerced to integer.

  • <stbl-error-incompatible_values-integer> when some values cannot be safely converted to integer.

  • <stbl-error-bad_null> for NULL values when allow_null = FALSE.

  • <stbl-error-bad_na> for NA values when allow_na = FALSE.

  • <stbl-error-size_too_small> when the vector is shorter than min_size.

  • <stbl-error-size_too_large> when the vector is longer than max_size.

  • <stbl-error-duplicate_elements> when unique = TRUE and duplicates are present.

  • <stbl-error-outside_range> when values fall outside min_value or max_value.

  • <stbl-error-allowed_values> when values are not in allowed_values.

See also

Other integer functions: are_int_ish(), specify_int(), stabilize_int_scalar(), to(), to_int(), to_int_scalar()

Other stabilization functions: 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_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

stabilize_int(1:10)
#>  [1]  1  2  3  4  5  6  7  8  9 10
stabilize_int("1")
#> [1] 1
stabilize_int(1 + 0i)
#> [1] 1
stabilize_int(NULL)
#> NULL
try(stabilize_int(NULL, allow_null = FALSE))
#> Error in eval(expr, envir) : `NULL` must not be <NULL>.
try(stabilize_int(c(1, NA), allow_na = FALSE))
#> Error in eval(expr, envir) : 
#>   `c(1, NA)` must not contain NA values.
#> • NA locations: 2
try(stabilize_int(letters))
#> Error in eval(expr, envir) : 
#>   `letters` <character> must be coercible to <integer>
#> ✖ Can't convert some values due to incompatible values.
#> • Locations: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, …,
#>   25, and 26
#> • Values: "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n",
#>   "o", "p", "q", "r", …, "y", and "z"
try(stabilize_int("1", coerce_character = FALSE))
#> Error in eval(expr, envir) : 
#>   Can't coerce `"1"` <character> to <integer>.
try(stabilize_int(factor(c("1", "a"))))
#> Error in eval(expr, envir) : 
#>   `factor(c("1", "a"))` <factor> must be coercible to <integer>
#> ✖ Can't convert some values due to incompatible values.
#> • Locations: 2
#> • Values: "a"
try(stabilize_int(factor("1"), coerce_factor = FALSE))
#> Error in eval(expr, envir) : 
#>   Can't coerce `factor("1")` <factor> to <integer>.
try(stabilize_int(1:10, min_value = 3))
#> Error in eval(expr, envir) : `1:10` must be >= 3.
#> ℹ Some values are too low.
#> ✖ Locations: 1 and 2
#> ✖ Values: 1 and 2
try(stabilize_int(1:10, max_value = 7))
#> Error in eval(expr, envir) : `1:10` must be <= 7.
#> ℹ Some values are too high.
#> ✖ Locations: 8, 9, and 10
#> ✖ Values: 8, 9, and 10
try(stabilize_int(1:5, allowed_values = c(1L, 2L, 3L)))
#> Error in eval(expr, envir) : 
#>   `1:5` must be one of the allowed values.
#> ℹ Allowed values: "1", "2", and "3".
#> ✖ Unexpected locations: 4 and 5
#> ✖ Unexpected values: "4" and "5".