Ensure list elements are of a specific size and recycle them if not

If any of the data-masked named expressions in ... are not the specified size, then the object attempts to be recycled to the size specified in the expression. .names and .size arguments can be used to check for given names and size of the list. The checking of size and the recycling are from the vctrs package (using vctrs::vec_size and vctrs::vec_recycle) and thus apply the vctrs recycling rules.

Usage

schema_recycle(.data, ...)

# S3 method for class 'list'
schema_recycle(
  .data,
  ...,
  .names = NULL,
  .size = NULL,
  .class = NULL,
  .error_call = caller_env()
)

Arguments

.data

a list to check the lengths schema of.

...

any number of data-masking name-value pairs to be evaluated using .data as a data-mask. Should follow the format of name = expected_size, e.g, var_x = 10L or var_x = var_y.

.names

optional character vector of names which must be present in the data.frame/list.

.size

optional scalar integerish value for the size that the data.frame/list must have.

.class

class to assign to the error (passed to rlang::abort).

.error_call

the call environment to use for the error (passed to rlang::abort).

Details

See also schema and schema_recycle, as well as cast_if_not for a non-data-masked version of casting.

Examples

# NB: Some of these examples are expected to produce an error. To
#     prevent them from terminating a run with example() they are
#     piped into a call to try().

li <- list(x = 1, y = "hi", z = 1:2)
# li$x and li$y are recycled.
li |>
  schema_recycle(x = 5, y = 3)
#> $x
#> [1] 1 1 1 1 1
#> 
#> $y
#> [1] "hi" "hi" "hi"
#> 
#> $z
#> [1] 1 2
#> 

li |>
  schema_recycle(z = 5) |>
  try()
#> Error in eval(expr, envir) : Error in `schema_recycle()`
#> ℹ Can't recycle `z` (size 2) to size 5.
# => Error: Can't recycle `z` (size 2) to size 5.

li |>
  schema_recycle(x = "hi") |>
  try()
#> Error in eval(expr, envir) : Error in
#> ℹ Size argument for `x` is not numeric: class <character>.
# => Size argument for `z` is not numeric: class <character>.

# schema_recycle works sequentially with quosures, so references to objects will
# be after they have been evaluated:
li |>
  schema_recycle(x = vctrs::vec_size(z), y = vctrs::vec_size(x))
#> $x
#> [1] 1 1
#> 
#> $y
#> [1] "hi" "hi"
#> 
#> $z
#> [1] 1 2
#> 

li |>
  schema_recycle(x = 1, .size = 5) |>
  try()
#> Error in eval(expr, envir) : Error in `schema_recycle()`
#> ℹ Object `li` must have vctrs size `5`, not `3`.
# => Error: Object `li` must have vctrs size `5`, not `3`.

li |>
  schema_recycle(x = 1, .names = c("x", "p")) |>
  try()
#> Error in eval(expr, envir) : Error in `schema_recycle()`
#> ℹ Objects `p` not found in `li`.
# => Error: Names `p` not found in `li`.

# injection and glue can be used to supply expressions, names, and messages:
li <- list(x = 1, z = 5)
x_name <- "x"
schema_recycle(li, !!x_name := z)
#> $x
#> [1] 1 1 1 1 1
#> 
#> $z
#> [1] 5
#> 
li$x <- 1:2
xg_name <- "{x_name}"
schema_recycle(li, {{ xg_name }} := 10) |> try()
#> Error in eval(expr, envir) : Error in `schema_recycle()`
#> ℹ Can't recycle `x` (size 2) to size 10.
# => Error: Can't recycle `x` (size 2) to size 10.