vec_recycle(x, size)
recycles a single vector to given size.
vec_recycle_common(...)
recycles multiple vectors to their common size.
All functions obey the vctrs recycling rules, described below, and will
throw an error if recycling is not possible. See vec_size()
for the
precise definition of size.
Usage
vec_recycle(x, size, ..., x_arg = "", call = caller_env())
vec_recycle_common(..., .size = NULL, .arg = "", .call = caller_env())
Arguments
- x
A vector to recycle.
- size
Desired output size.
- ...
For
vec_recycle_common()
, vectors to recycle.For
vec_recycle()
, these dots should be empty.
- x_arg
Argument name for
x
. These are used in error messages to inform the user about which argument has an incompatible size.- call
The execution environment of a currently running function, e.g.
caller_env()
. The function will be mentioned in error messages as the source of the error. See thecall
argument ofabort()
for more information.- .size
Desired output size. If omitted, will use the common size from
vec_size_common()
.- .arg
An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.
- .call
The execution environment of a currently running function, e.g.
caller_env()
. The function will be mentioned in error messages as the source of the error. See thecall
argument ofabort()
for more information.
Recycling rules
The common size of two vectors defines the recycling rules, and can be summarise with the following table:
(Note NULL
s are handled specially; they are treated like empty
arguments and hence don't affect the size)
This is a stricter set of rules than base R, which will usually
return output of length max(nx, ny)
, warning if the length of the longer
vector is not an integer multiple of the length of the shorter.
We say that two vectors have compatible size if they can be recycled to be the same length.
Examples
# Inputs with 1 observation are recycled
vec_recycle_common(1:5, 5)
#> [[1]]
#> [1] 1 2 3 4 5
#>
#> [[2]]
#> [1] 5 5 5 5 5
#>
vec_recycle_common(integer(), 5)
#> [[1]]
#> integer(0)
#>
#> [[2]]
#> numeric(0)
#>
if (FALSE) {
vec_recycle_common(1:5, 1:2)
}
# Data frames and matrices are recycled along their rows
vec_recycle_common(data.frame(x = 1), 1:5)
#> [[1]]
#> x
#> 1 1
#> 2 1
#> 3 1
#> 4 1
#> 5 1
#>
#> [[2]]
#> [1] 1 2 3 4 5
#>
vec_recycle_common(array(1:2, c(1, 2)), 1:5)
#> [[1]]
#> [,1] [,2]
#> [1,] 1 2
#> [2,] 1 2
#> [3,] 1 2
#> [4,] 1 2
#> [5,] 1 2
#>
#> [[2]]
#> [1] 1 2 3 4 5
#>
vec_recycle_common(array(1:3, c(1, 3, 1)), 1:5)
#> [[1]]
#> , , 1
#>
#> [,1] [,2] [,3]
#> [1,] 1 2 3
#> [2,] 1 2 3
#> [3,] 1 2 3
#> [4,] 1 2 3
#> [5,] 1 2 3
#>
#>
#> [[2]]
#> [1] 1 2 3 4 5
#>