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.

• If an error occurs while generating results, the iterator's internal state is not guaranteed to remain at its previous position. Call startOver() before continuing to use the iterator.

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 Oct. 18, 2026, 1:06 a.m.