Construct Parameters for a Sequence Based on Margins

cp_seq() returns a list of parameters to construct a sequence based on the margins of an object.
It is internally used by the idx_r function and slice method.

Usage

cp_seq(x, m = 0L, from = NULL, to = NULL, by = 1L)

Arguments

x: the object for which to compute margin-based sequence parameters.
m: integer or complex, giving the margin(s).
For non-dimensional objects or for flat indices, specify m = 0L.
from: integer or complex, of the same length as m or of length 1, specifying the from point.
to: integer or complex, of the same length as m or of length 1, specifying the maximally allowed end value.
by: integer, of the same length as m or of length 1, specifying the step size.

Value

A list of the following elements:

$start:

The actual starting point of the sequence.

This is simply from translated to regular numeric.

$end:

The actual ending point of the sequence.

This is not the same as to.

For example, the following code:

seq(from = 1L, to = 10L, by = 2L)
#> [1] 1 3 5 7 9

specifies to = 10L.

But the sequence doesn't actually end at 10; it ends at 9.

Therefore, cp_seq(x, m, 1, 10, 2) will return end = 9, not end = 10.

This allows the user to easily predict where an sequence given in idx_r/slice will actually end.

$by:

This will give by, but with it's sign adjusted, if needed.

$length.out:

The actual vector lengths the sequences would be, given the translated parameters.

Arguments Details

Multiple dimensions at once
The cp_seq function can construct the sequence parameters needed for multiple dimensions at once, by specifying a vector for m.
The lengths of the other arguments are then recycled if needed.

Using only by
If from, to are not specified, using by will construct the following sequence:
If by is positive, seq.int(1L, n, by).
If by is negative, seq.int(n, 1L, by).
Where n is the maximum index (i.e. length(x) or dim(x)[m], depending on the situation).

Using from, to, by
If from, to, by are all specified, by is stored as abs(by), and the sign of by is automatically adjusted to ensure a sensible sequence is created.

Examples


x <- data.frame(
  a = 1:10, b = letters[1:10], c = factor(letters[1:10]), d = -1:-10
)
print(x)
#>     a b c   d
#> 1   1 a a  -1
#> 2   2 b b  -2
#> 3   3 c c  -3
#> 4   4 d d  -4
#> 5   5 e e  -5
#> 6   6 f f  -6
#> 7   7 g g  -7
#> 8   8 h h  -8
#> 9   9 i i  -9
#> 10 10 j j -10
ind1 <- idx_r(x, 1, 2, 2* -1i) # rows 2:(nrow(x)-1)
sb2_x(x, ind1) # extract the row range
#>   a b c  d
#> 1 2 b b -2
#> 2 3 c c -3
#> 3 4 d d -4
#> 4 5 e e -5
#> 5 6 f f -6
#> 6 7 g g -7
#> 7 8 h h -8
#> 8 9 i i -9

x <- array(1:125, c(5,5,5))
dims <- 1:3
sub <- idx_r(x, dims, 2, 2* -1i) # 2:(n-1) for every dimension
sb_x(x, sub, dims) # same as x[ 2:4, 2:4, 2:4, drop = FALSE]
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]   32   37   42
#> [2,]   33   38   43
#> [3,]   34   39   44
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3]
#> [1,]   57   62   67
#> [2,]   58   63   68
#> [3,]   59   64   69
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3]
#> [1,]   82   87   92
#> [2,]   83   88   93
#> [3,]   84   89   94
#> 

x <- letters
x[idx_r(x, 0, 2, 2* -1i)]
#>  [1] "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" "t"
#> [20] "u" "v" "w" "x" "y"