expandGridIterator: expandGrid Iterator

In RcppAlgos: High Performance Tools for Combinatorics and Computational Mathematics

expandGrid Iterator

Description

• Returns an iterator for iterating over the Cartesian product of the input vectors.

• Supports random access via the [[ method.

• GMP support allows for exploration of cases where the number of products is large.

• Use the next methods to obtain results in lexicographical order.

Usage

expandGridIter(..., nThreads = NULL, return_df = FALSE)

Arguments

...	vectors, factors or a list containing these. (See ?expand.grid).
nThreads	Specific number of threads to be used. The default is NULL.
return_df	Logical flag to force the output to be a data.frame. The default is FALSE.

Details

Once you initialize a new iterator, the following methods are available:

nextIter

Retrieve the next lexicographical result

nextNIter

Pass an integer n to retrieve the next n lexicographical results

nextRemaining

Retrieve all remaining lexicographical results

currIter

Returns the current iteration

startOver

Resets the iterator

sourceVector

View the source input

summary

Returns a list of summary information about the iterator

front

Retrieve the first lexicographical result

back

Retrieve the last lexicographical result

[[

Random access method. Pass a single value or a vector of valid indices. If a single value is passed, the internal index of the iterator will be updated, however if a vector is passed the internal state will not change. GMP support allows for flexible indexing.

Value

• If nextIter is called, a named vector is returned if a matrix can be returned in the general case. Otherwise, a data.frame is returned.

• When nextNIter and nextRemaining are called, a named matrix is returned when all of the input is of the same type and return_df = FALSE. Otherwise, a data.frame is returned.

Note

• If nThreads is utilized, it will only take effect if the number of elements requested is greater than some threshold (determined internally). E.g:

  serial   <- expandGridIter(Map(\(x, y) x:y, 1:10, 11:20))
  multi    <- expandGridIter(Map(\(x, y) x:y, 1:10, 11:20), nThreads = 4)
  fetch1e6 <- multi@nextNIter(1e6)  ## much faster than serial@nextNIter(1e6)
  fetch1e3 <- multi@nextNIter(1e3)  ## only one thread used... same as serial@nextNIter(1e3)
  
  library(microbenchmark)
  microbenchmark(multi@nextNIter(1e6), serial@nextNIter(1e6), times = 20)
  microbenchmark(multi@nextNIter(1e3), serial@nextNIter(1e3), times = 20)

• The maximum number of expandGrid that can be generated at one time is 2^{31} - 1.

Author(s)

Joseph Wood

See Also

expandGrid

Examples

a = expandGridIter(factor(state.abb), euro, islands)
a@nextIter()
a@nextNIter(3)
a@front()
all_remaining = a@nextRemaining()
dim(all_remaining)
a@summary()
a@back()
a[[5]]
a@summary()
a[[c(1, 17, 3)]]
a@summary()

RcppAlgos documentation built on March 8, 2026, 9:08 a.m.