Skip to contents

Ensure an integer argument meets expectations

Source: R/stabilize_int.R, R/stabilize_int_scalar.R, R/to_int.R, and 1 more
stabilize_int.Rd

to_int() checks whether an argument can be coerced to integer without losing information, returning it silently if so. Otherwise an informative error message is signaled.

stabilize_int() can check more details about the argument, but is slower than to_int().

stabilize_int_scalar() and to_int_scalar() are optimized to check for length-1 integer vectors.

Usage

stabilize_int(
  x,
  ...,
  allow_null = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_size = NULL,
  max_size = NULL,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilize_int_scalar(
  x,
  ...,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  allow_na = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  min_value = NULL,
  max_value = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_int(
  x,
  allow_null = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

to_int_scalar(
  x,
  allow_null = TRUE,
  allow_zero_length = TRUE,
  coerce_character = TRUE,
  coerce_factor = TRUE,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

x

The argument to stabilize.

...

These dots are for future extensions and should be empty.

allow_null

Logical. Is NULL an acceptable value?

allow_na

Logical. Are NA values ok?

coerce_character

Logical. Should character vectors such as "1" and "2.0" be coerced to integer?

coerce_factor

Logical. Should factors with values such as "1" and "2.0" be coerced to integer? Note that this function uses the character value from the factor, while as.integer() uses the integer index of the factor.

min_size

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

max_size

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

min_value

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

max_value

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

x_arg

Character. An argument name for x. 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

The execution environment of the call. See the call argument of rlang::abort() for more information.

x_class

Character. The class name of x to use in error messages. Use this if you remove a special class from x before checking its coercion, but want the error message to match the original class.

allow_zero_length

Logical. Are zero-length vectors acceptable?

Value

The argument as an integer.

Examples

to_int(1:10)
#>  [1]  1  2  3  4  5  6  7  8  9 10
to_int("1")
#> [1] 1
to_int(1 + 0i)
#> [1] 1
to_int(NULL)
#> NULL
try(to_int(c(1, 2, 3.1, 4, 5.2)))
#> Error in eval(expr, envir, enclos) : 
#>   Can't convert from `c(1, 2, 3.1, 4, 5.2)` <double> to <integer> due to loss of precision.
#> • Locations: 3, 5
try(to_int("1", coerce_character = FALSE))
#> Error in eval(expr, envir, enclos) : 
#>   Can't coerce `"1"` <character> to <integer>.
try(to_int(c("1", "2", "3.1", "4", "5.2")))
#> Error in eval(expr, envir, enclos) : 
#>   `c("1", "2", "3.1", "4", "5.2")` <character> must be coercible to
#> <integer>
#> ✖ Can't convert some values due to loss of precision.
#> • Locations: 3 and 5

to_int_scalar("1")
#> [1] 1
try(to_int_scalar(1:10))
#> Error in eval(expr, envir, enclos) : 
#>   `1:10` must be a single <integer>.
#> ✖ `1:10` has 10 values.

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, enclos) : 
#>   `NULL` must not be <NULL>.
try(stabilize_int(c(1, NA), allow_na = FALSE))
#> Error in eval(expr, envir, enclos) : 
#>   `c(1, NA)` must not contain NA values.
#> • NA locations: 2
try(stabilize_int(letters))
#> Error in eval(expr, envir, enclos) : 
#>   `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
try(stabilize_int("1", coerce_character = FALSE))
#> Error in eval(expr, envir, enclos) : 
#>   Can't coerce `"1"` <character> to <integer>.
try(stabilize_int(factor(c("1", "a"))))
#> Error in eval(expr, envir, enclos) : 
#>   `factor(c("1", "a"))` <factor> must be coercible to <integer>
#> ✖ Can't convert some values due to incompatible values.
#> • Locations: 2
try(stabilize_int(factor("1"), coerce_factor = FALSE))
#> Error in eval(expr, envir, enclos) : 
#>   Can't coerce `factor("1")` <factor> to <integer>.
try(stabilize_int(1:10, min_value = 3))
#> Error in eval(expr, envir, enclos) : 
#>   ! Values of `1:10` must be >= 3.
#> ✖ Values are too low at locations 1 and 2.
try(stabilize_int(1:10, max_value = 7))
#> Error in eval(expr, envir, enclos) : 
#>   ! Values of `1:10` must be <= 7.
#> ✖ Values are too high at locations 8, 9, and 10.

stabilize_int_scalar(1L)
#> [1] 1
stabilize_int_scalar("1")
#> [1] 1
try(stabilize_int_scalar(1:10))
#> Error in eval(expr, envir, enclos) : 
#>   `1:10` must be a single <integer>.
#> ✖ `1:10` has 10 values.
stabilize_int_scalar(NULL)
#> NULL
try(stabilize_int_scalar(NULL, allow_null = FALSE))
#> Error in eval(expr, envir, enclos) : 
#>   `NULL` must not be <NULL>.