Iterator that returns the elements of an object along with their indices

Constructs an iterator that returns the elements of an object along with each element's indices. Enumeration is useful when looping through an object and a counter is required.

The i_enumerate method for arrays allows splitting an array by arbitrary margins, including by multiple margins. The index element returned will be a vector (or if chunking is used, a matrix) of indices.

Usage

i_enumerate(obj, ...)

ienumerate(obj, ...)

# S3 method for default
i_enumerate(obj, ..., recycle = FALSE, chunkSize, chunks)

i_enum(obj, ...)

# S3 method for array
i_enumerate(
  obj,
  ...,
  recycle = FALSE,
  chunkSize,
  chunks,
  by = c("cell", "row", "column"),
  rowMajor = TRUE,
  drop = FALSE
)

Arguments

obj: object to return indefinitely.
...: Undocumented.
recycle: Whether to restart the iterator after finishing the array.
chunkSize: How large a chunk to take along the specified dimension.
chunks: How many chunks to divide the array into.
by: Which array margins to iterate over. Can be "row", "col", "cell", or a vector of numerical indices.
rowMajor: If TRUE, the first index varies fastest, if FALSE, the last index varies fastest.
drop: Whether to drop marginalized dimensions. If chunking is used, this has no effect.

Value

iterator that returns the values of obj along with the index of the object.

Details

This function is intended to follow the convention used in Python's enumerate function where the primary difference is that a list is returned instead of Python's tuple construct.

Each call to nextElem returns a list with two elements:

index:: a counter
value:: the current value of object

i_enum is an alias to i_enumerate to save a few keystrokes.

First appeared in package iterators2.

These are two closely closely related functions: i_enumerate accepts an iterable, and will only emit a single index starting with 1. ienumerate is a generic with methods for vectors and arrays, supporting all chunking and recycling options, and returning multiple indices for arrays.

Author

Peter Meilstrup

Examples

set.seed(42)
it <- i_enumerate(rnorm(5))
as.list(it)
#> [[1]]
#> [[1]]$index
#> [1] 1
#> 
#> [[1]]$value
#> [1] 1.370958
#> 
#> 
#> [[2]]
#> [[2]]$index
#> [1] 2
#> 
#> [[2]]$value
#> [1] -0.5646982
#> 
#> 
#> [[3]]
#> [[3]]$index
#> [1] 3
#> 
#> [[3]]$value
#> [1] 0.3631284
#> 
#> 
#> [[4]]
#> [[4]]$index
#> [1] 4
#> 
#> [[4]]$value
#> [1] 0.6328626
#> 
#> 
#> [[5]]
#> [[5]]$index
#> [1] 5
#> 
#> [[5]]$value
#> [1] 0.4042683
#> 
#> 

# Iterates through the columns of the iris data.frame
it2 <- i_enum(iris)
nextOr(it2, NA)
#> $index
#> [1] 1
#> 
#> $value
#>   [1] 5.1 4.9 4.7 4.6 5.0 5.4 4.6 5.0 4.4 4.9 5.4 4.8 4.8 4.3 5.8 5.7 5.4 5.1
#>  [19] 5.7 5.1 5.4 5.1 4.6 5.1 4.8 5.0 5.0 5.2 5.2 4.7 4.8 5.4 5.2 5.5 4.9 5.0
#>  [37] 5.5 4.9 4.4 5.1 5.0 4.5 4.4 5.0 5.1 4.8 5.1 4.6 5.3 5.0 7.0 6.4 6.9 5.5
#>  [55] 6.5 5.7 6.3 4.9 6.6 5.2 5.0 5.9 6.0 6.1 5.6 6.7 5.6 5.8 6.2 5.6 5.9 6.1
#>  [73] 6.3 6.1 6.4 6.6 6.8 6.7 6.0 5.7 5.5 5.5 5.8 6.0 5.4 6.0 6.7 6.3 5.6 5.5
#>  [91] 5.5 6.1 5.8 5.0 5.6 5.7 5.7 6.2 5.1 5.7 6.3 5.8 7.1 6.3 6.5 7.6 4.9 7.3
#> [109] 6.7 7.2 6.5 6.4 6.8 5.7 5.8 6.4 6.5 7.7 7.7 6.0 6.9 5.6 7.7 6.3 6.7 7.2
#> [127] 6.2 6.1 6.4 7.2 7.4 7.9 6.4 6.3 6.1 7.7 6.3 6.4 6.0 6.9 6.7 6.9 5.8 6.8
#> [145] 6.7 6.7 6.3 6.5 6.2 5.9
#> 
nextOr(it2, NA)
#> $index
#> [1] 2
#> 
#> $value
#>   [1] 3.5 3.0 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 3.7 3.4 3.0 3.0 4.0 4.4 3.9 3.5
#>  [19] 3.8 3.8 3.4 3.7 3.6 3.3 3.4 3.0 3.4 3.5 3.4 3.2 3.1 3.4 4.1 4.2 3.1 3.2
#>  [37] 3.5 3.6 3.0 3.4 3.5 2.3 3.2 3.5 3.8 3.0 3.8 3.2 3.7 3.3 3.2 3.2 3.1 2.3
#>  [55] 2.8 2.8 3.3 2.4 2.9 2.7 2.0 3.0 2.2 2.9 2.9 3.1 3.0 2.7 2.2 2.5 3.2 2.8
#>  [73] 2.5 2.8 2.9 3.0 2.8 3.0 2.9 2.6 2.4 2.4 2.7 2.7 3.0 3.4 3.1 2.3 3.0 2.5
#>  [91] 2.6 3.0 2.6 2.3 2.7 3.0 2.9 2.9 2.5 2.8 3.3 2.7 3.0 2.9 3.0 3.0 2.5 2.9
#> [109] 2.5 3.6 3.2 2.7 3.0 2.5 2.8 3.2 3.0 3.8 2.6 2.2 3.2 2.8 2.8 2.7 3.3 3.2
#> [127] 2.8 3.0 2.8 3.0 2.8 3.8 2.8 2.8 2.6 3.0 3.4 3.1 3.0 3.1 3.1 3.1 2.7 3.2
#> [145] 3.3 3.0 2.5 3.0 3.4 3.0
#> 
nextOr(it2, NA)
#> $index
#> [1] 3
#> 
#> $value
#>   [1] 1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 1.5 1.6 1.4 1.1 1.2 1.5 1.3 1.4
#>  [19] 1.7 1.5 1.7 1.5 1.0 1.7 1.9 1.6 1.6 1.5 1.4 1.6 1.6 1.5 1.5 1.4 1.5 1.2
#>  [37] 1.3 1.4 1.3 1.5 1.3 1.3 1.3 1.6 1.9 1.4 1.6 1.4 1.5 1.4 4.7 4.5 4.9 4.0
#>  [55] 4.6 4.5 4.7 3.3 4.6 3.9 3.5 4.2 4.0 4.7 3.6 4.4 4.5 4.1 4.5 3.9 4.8 4.0
#>  [73] 4.9 4.7 4.3 4.4 4.8 5.0 4.5 3.5 3.8 3.7 3.9 5.1 4.5 4.5 4.7 4.4 4.1 4.0
#>  [91] 4.4 4.6 4.0 3.3 4.2 4.2 4.2 4.3 3.0 4.1 6.0 5.1 5.9 5.6 5.8 6.6 4.5 6.3
#> [109] 5.8 6.1 5.1 5.3 5.5 5.0 5.1 5.3 5.5 6.7 6.9 5.0 5.7 4.9 6.7 4.9 5.7 6.0
#> [127] 4.8 4.9 5.6 5.8 6.1 6.4 5.6 5.1 5.6 6.1 5.6 5.5 4.8 5.4 5.6 5.1 5.1 5.9
#> [145] 5.7 5.2 5.0 5.2 5.4 5.1
#> 
nextOr(it2, NA)
#> $index
#> [1] 4
#> 
#> $value
#>   [1] 0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 0.2 0.2 0.1 0.1 0.2 0.4 0.4 0.3
#>  [19] 0.3 0.3 0.2 0.4 0.2 0.5 0.2 0.2 0.4 0.2 0.2 0.2 0.2 0.4 0.1 0.2 0.2 0.2
#>  [37] 0.2 0.1 0.2 0.2 0.3 0.3 0.2 0.6 0.4 0.3 0.2 0.2 0.2 0.2 1.4 1.5 1.5 1.3
#>  [55] 1.5 1.3 1.6 1.0 1.3 1.4 1.0 1.5 1.0 1.4 1.3 1.4 1.5 1.0 1.5 1.1 1.8 1.3
#>  [73] 1.5 1.2 1.3 1.4 1.4 1.7 1.5 1.0 1.1 1.0 1.2 1.6 1.5 1.6 1.5 1.3 1.3 1.3
#>  [91] 1.2 1.4 1.2 1.0 1.3 1.2 1.3 1.3 1.1 1.3 2.5 1.9 2.1 1.8 2.2 2.1 1.7 1.8
#> [109] 1.8 2.5 2.0 1.9 2.1 2.0 2.4 2.3 1.8 2.2 2.3 1.5 2.3 2.0 2.0 1.8 2.1 1.8
#> [127] 1.8 1.8 2.1 1.6 1.9 2.0 2.2 1.5 1.4 2.3 2.4 1.8 1.8 2.1 2.4 2.3 1.9 2.3
#> [145] 2.5 2.3 1.9 2.0 2.3 1.8
#> 
nextOr(it2, NA)
#> $index
#> [1] 5
#> 
#> $value
#>   [1] setosa     setosa     setosa     setosa     setosa     setosa    
#>   [7] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [13] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [19] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [25] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [31] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [37] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [43] setosa     setosa     setosa     setosa     setosa     setosa    
#>  [49] setosa     setosa     versicolor versicolor versicolor versicolor
#>  [55] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [61] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [67] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [73] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [79] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [85] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [91] versicolor versicolor versicolor versicolor versicolor versicolor
#>  [97] versicolor versicolor versicolor versicolor virginica  virginica 
#> [103] virginica  virginica  virginica  virginica  virginica  virginica 
#> [109] virginica  virginica  virginica  virginica  virginica  virginica 
#> [115] virginica  virginica  virginica  virginica  virginica  virginica 
#> [121] virginica  virginica  virginica  virginica  virginica  virginica 
#> [127] virginica  virginica  virginica  virginica  virginica  virginica 
#> [133] virginica  virginica  virginica  virginica  virginica  virginica 
#> [139] virginica  virginica  virginica  virginica  virginica  virginica 
#> [145] virginica  virginica  virginica  virginica  virginica  virginica 
#> Levels: setosa versicolor virginica
#> 

a <- array(1:27, c(3, 3, 3))
as.list(i_enumerate(a, by=c(1, 2), drop=TRUE))
#> [[1]]
#> [[1]]$index
#> [1] 1 1
#> 
#> [[1]]$value
#> [1]  1 10 19
#> 
#> 
#> [[2]]
#> [[2]]$index
#> [1] 2 1
#> 
#> [[2]]$value
#> [1]  2 11 20
#> 
#> 
#> [[3]]
#> [[3]]$index
#> [1] 3 1
#> 
#> [[3]]$value
#> [1]  3 12 21
#> 
#> 
#> [[4]]
#> [[4]]$index
#> [1] 1 2
#> 
#> [[4]]$value
#> [1]  4 13 22
#> 
#> 
#> [[5]]
#> [[5]]$index
#> [1] 2 2
#> 
#> [[5]]$value
#> [1]  5 14 23
#> 
#> 
#> [[6]]
#> [[6]]$index
#> [1] 3 2
#> 
#> [[6]]$value
#> [1]  6 15 24
#> 
#> 
#> [[7]]
#> [[7]]$index
#> [1] 1 3
#> 
#> [[7]]$value
#> [1]  7 16 25
#> 
#> 
#> [[8]]
#> [[8]]$index
#> [1] 2 3
#> 
#> [[8]]$value
#> [1]  8 17 26
#> 
#> 
#> [[9]]
#> [[9]]$index
#> [1] 3 3
#> 
#> [[9]]$value
#> [1]  9 18 27
#> 
#> 
as.list(i_enumerate(a, by=c(3), drop=FALSE))
#> [[1]]
#> [[1]]$index
#> [1] 1
#> 
#> [[1]]$value
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]    1    4    7
#> [2,]    2    5    8
#> [3,]    3    6    9
#> 
#> 
#> 
#> [[2]]
#> [[2]]$index
#> [1] 2
#> 
#> [[2]]$value
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]   10   13   16
#> [2,]   11   14   17
#> [3,]   12   15   18
#> 
#> 
#> 
#> [[3]]
#> [[3]]$index
#> [1] 3
#> 
#> [[3]]$value
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]   19   22   25
#> [2,]   20   23   26
#> [3,]   21   24   27
#> 
#> 
#> 
as.list(i_enumerate(a, by=c(2, 3), chunkSize=7))
#> [[1]]
#> [[1]]$index
#>      [,1] [,2]
#> [1,]    1    1
#> [2,]    2    1
#> [3,]    3    1
#> [4,]    1    2
#> [5,]    2    2
#> [6,]    3    2
#> [7,]    1    3
#> 
#> [[1]]$value
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,]    1    4    7   10   13   16   19
#> [2,]    2    5    8   11   14   17   20
#> [3,]    3    6    9   12   15   18   21
#> 
#> 
#> 
#> [[2]]
#> [[2]]$index
#>      [,1] [,2]
#> [1,]    2    3
#> [2,]    3    3
#> 
#> [[2]]$value
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]   22   25
#> [2,]   23   26
#> [3,]   24   27
#> 
#> 
#>