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 ienumerate 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

ienumerate(obj, ...)

ienum(obj, ...)

# S3 method for array
ienumerate(
  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

ienum is an alias to ienumerate to save a few keystrokes.

First appeared in package iterators2.

Author

Peter Meilstrup

Examples

set.seed(42)
it <- ienumerate(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 <- ienum(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(ienumerate(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(ienumerate(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(ienumerate(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
#> 
#> 
#>