Package: java.util

## [Java] Interface Iterator

-     public interface Iterator

  GDK enhancements for Iterator.

  displayName:
    Iterator
  receiverFqcn:
    java.util.Iterator

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public boolean` | `any(Closure predicate)` Iterates over the contents of an iterator, and checks whether a predicate is valid for at least one element.
    `` | `public boolean` | `asBoolean()` Coerce an iterator instance to a boolean value.
    `` | `public Object` | `average()` Averages the items from an Iterator.
    `<T>` | `public Object` | `average(Closure closure)` Averages the result of applying a closure to each item returned from an iterator.
    `<T>` | `public BufferedIterator<T>` | `buffered()` Returns a `BufferedIterator` that allows examining the next element without consuming it.
    `<T>` | `public Iterator<List<T>>` | `chop(int chopSizes)` Chops the iterator items into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public Iterator<List<T>>` | `chop(boolean returnEarly, int chopSizes)` Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public Iterator<List<T>>` | `chop(Iterator<Integer> chopSizes)` Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public Iterator<List<T>>` | `chop(boolean returnEarly, Iterator<Integer> chopSizes)` Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public Iterator<List<T>>` | `collate(int size, int step, boolean keepRemainder)` Collates this iterator into sub-lists of length `size` stepping through the code `step` elements for each sub-list.
    `<T>` | `public Iterator<List<T>>` | `collate(int size, int step)` Collates this iterator into sub-lists of length `size` stepping through the code `step` elements for each sub-list including any remaining elements as the last sub-list.
    `<T>` | `public Iterator<List<T>>` | `collate(int size, boolean keepRemainder)` Collates this iterator into sub-lists of length `size`.
    `<T>` | `public Iterator<List<T>>` | `collate(int size)` Collates this iterator into sub-lists of length `size` including any remaining elements as the last sub-list.
    `<E, T>` | `public List<T>` | `collect(Closure<T> transform)` Iterates through this Iterator transforming each item into a new value using the `transform` closure, returning a list of transformed values.
    `<E, T, C>` | `public C` | `collect(C collector, Closure<? extends T> transform)` Iterates through this Iterator transforming each item into a new value using the `transform` closure and adding it to the supplied `collector`.
    `<T>` | `public List<T>` | `collect()` Convert an iterator to a List.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Closure<?> transform)` A variant of collectEntries for Iterators.
    `<K, V>` | `public Map<K, V>` | `collectEntries()` A variant of collectEntries for Iterators using the identity closure as the transform.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector, Closure<?> transform)` A variant of collectEntries for Iterators using a supplied map as the destination of transformed entries.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector, Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)` A variant of collectEntries for Iterators with separate functions for transforming the keys and values.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)` A variant of collectEntries for Iterators with separate functions for transforming the keys and values.
    `<K, V>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector)` A variant of collectEntries for Iterators using the identity closure as the transform and a supplied map as the destination of transformed entries.
    `<T, E, C>` | `public C` | `collectMany(C collector, Closure<? extends Collection<? extends T>> projection)` Projects each item from a source iterator to a collection and concatenates (flattens) the resulting collections into a single list.
    `<T, E>` | `public List<T>` | `collectMany(Closure<? extends Collection<? extends T>> projection)` Projects each item from a source iterator to a collection and concatenates (flattens) the resulting collections into a single list.
    `<T, E>` | `public List<T>` | `collectMany()` Flattens an iterator of collections into a single list.
    `<E, T>` | `public Iterator<T>` | `collecting(Closure<T> transform)` Returns an iterator of transformed values from the source iterator using the `transform` closure.
    `<K, V, E>` | `public Iterator<Entry<K, V>>` | `collectingEntries(Closure<?> transform)` Returns an iterator of transformed values from the source iterator using the `transform` closure.
    `<T, E>` | `public Iterator<T>` | `collectingMany(Closure<? extends Collection<? extends T>> projection)` Iterates through the elements produced by projecting and flattening the elements from a source iterator.
    `` | `public Number` | `count(Object value)` Counts the number of occurrences of the given value from the items within this Iterator.
    `<T>` | `public Number` | `count(Closure closure)` Counts the number of occurrences which satisfy the given closure from the items within this Iterator.
    `<T, E>` | `public E` | `count(E initialCount, Closure closure)` Counts the number of occurrences which satisfy the given closure from the items within this Iterator, adding the count to the initial count.
    `<K, E>` | `public Map<K, Integer>` | `countBy(Closure<K> closure)` Sorts all iterator items into groups determined by the supplied mapping closure and counts the group size.
    `<E>` | `public Map<E, Integer>` | `countBy()` Creates a multiset-like map of the iterator members.
    `<T>` | `public Iterator<T>` | `drop(int num)` Drops the given number of elements from the head of this iterator if they are available.
    `<T>` | `public Iterator<T>` | `dropRight(int num)` Drops the given number of elements from the tail of this Iterator.
    `<T>` | `public Iterator<T>` | `dropWhile(Closure<?> condition)` Creates an Iterator that returns a suffix of the elements from an original Iterator.
    `<T>` | `public Iterator<T>` | `each(Closure closure)` Iterates through an Iterator, passing each item to the given closure.
    `<T>` | `public Iterator<T>` | `eachWithIndex(Closure closure)` Iterates through an iterator type, passing each item and the item's index (a counter starting at zero) to the given closure.
    `<T>` | `public boolean` | `every(Closure predicate)` Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this iterator).
    `<T>` | `public int` | `findIndexOf(Closure condition)` Iterates over the elements of an Iterator and returns the index of the first item that satisfies the condition specified by the closure.
    `<T>` | `public int` | `findIndexOf(int startIndex, Closure condition)` Iterates over the elements of an Iterator, starting from a specified startIndex, and returns the index of the first item that satisfies the condition specified by the closure.
    `<T>` | `public Iterator<Number>` | `findIndexValues(Closure<?> transform)` Returns an iterator of transformed values from the source iterator using the `transform` closure.
    `<T>` | `public Iterator<Number>` | `findIndexValues(Number startIndex, Closure<?> transform)` Returns an iterator of transformed values from the source iterator using the `transform` closure and starting with index `startIndex`.
    `<T>` | `public int` | `findLastIndexOf(Closure condition)` Iterates over the elements of an Iterator and returns the index of the last item that matches the condition specified in the closure.
    `<T>` | `public int` | `findLastIndexOf(int startIndex, Closure condition)` Iterates over the elements of an Iterator, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.
    `<S, T, U, V>` | `public T` | `findResult(U defaultResult, Closure<V> condition)` Iterates through the Iterator calling the given closure condition for each item but stopping once the first non-null result is found and returning that result.
    `<T, U, V>` | `public T` | `findResult(V defaultResult)` Iterates through the Iterator stopping once the first non-null result is found and returning that result.
    `<T, U>` | `public T` | `findResult(Closure<T> condition)` Iterates through the Iterator calling the given closure condition for each item but stopping once the first non-null result is found and returning that result.
    `<T>` | `public T` | `findResult()` Iterates through the Iterator stopping once the first non-null result is found and returning that result.
    `<T, U>` | `public Collection<T>` | `findResults(Closure<T> filteringTransform)` Iterates through the Iterator transforming items using the supplied closure and collecting any non-null results.
    `<T>` | `public Collection<T>` | `findResults()` Iterates through the Iterator collecting any non-null results.
    `<T>` | `public Iterator<T>` | `findingAll(Closure<?> transform)` Lazily finds all items matching the closure condition.
    `<T, U>` | `public Iterator<T>` | `findingResults(Closure<T> filteringTransform)` Iterates through the Iterator transforming items using the supplied closure and finding any non-null results.
    `<T, E>` | `public Iterator<T>` | `flatten()` Flatten an Iterator.
    `<T, E>` | `public Iterator<T>` | `flatten(boolean flattenOptionals)` Flatten an Iterator.
    `<T, E>` | `public Iterator<T>` | `flatten(Closure<?> flattenUsing)` Flatten an Iterator.
    `<T, E>` | `public Iterator<T>` | `flatten(boolean flattenOptionals, Closure<?> flattenUsing)` Flatten an Iterator.
    `<T, E>` | `public Iterator<T>` | `flattenMany(boolean flattenOptionals, Closure<?> flattenUsing)` Flatten the elements from an Iterator.
    `<T>` | `public T` | `getAt(int idx)` Support the subscript operator for an Iterator.
    `<T>` | `public Iterator<T>` | `grepping(Object filter)` Lazily returns an Iterator of items matching the given filter - calling the `Object.isCase` method used by switch statements.
    `<T>` | `public Iterator<T>` | `grepping()` Lazily returns an Iterator of elements which satisfy Groovy truth.
    `<E>` | `public Iterator<Tuple2<Integer, E>>` | `indexed()` Zips an iterator with indices in (index, value) order.
    `<E>` | `public Iterator<Tuple2<Integer, E>>` | `indexed(int offset)` Zips an iterator with indices in (index, value) order.
    `<T>` | `public Iterator<T>` | `init()` Returns an Iterator containing all the items from this iterator except the last one.
    `<E, T, U, V>` | `public T` | `inject(U initialValue, Closure<V> closure)` Iterates through the given iterator, passing in the initial value to the closure along with the first item.
    `<E, T, U, V>` | `public Iterator<T>` | `injectAll(U initialValue, Closure<V> closure)` Iterates through the given iterator, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<E, T, V>` | `public Iterator<T>` | `injectAll(Closure<V> closure)` Iterates through the given iterator, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<T, U, V>` | `public Iterator<T>` | `interleave(Iterator<V> other)` An iterator of the elements from two Iterators interleaved.
    `<T, U, V>` | `public Iterator<T>` | `interleave(Iterator<V> other, boolean includeRemainder)` An iterator of the elements from two Iterators interleaved.
    `<T>` | `public boolean` | `isSorted()` Determines if the Iterator elements are sorted.
    `<T>` | `public boolean` | `isSorted(Comparator<? super T> comparator)` Determines if the Iterator elements are sorted according to the given Comparator.
    `<T>` | `public boolean` | `isSorted(Closure closure)` Determines if the Iterator elements are sorted using the given Closure to determine order.
    `<T>` | `public Iterator<T>` | `iterator()` Supports 'duck-typing' when trying to get an Iterator for each element of a Collection, some of which may already be an Iterator.
    `` | `public String` | `join()` Concatenates the `toString()` representation of each item from the Iterator.
    `` | `public String` | `join(String separator)` Concatenates the `toString()` representation of each item from the Iterator, with the given String as a separator between each item.
    `<T>` | `public T` | `max()` Adds max() method to Iterator objects.
    `<T>` | `public T` | `max(Comparator<? super T> comparator)` Selects the maximum value found from the Iterator using the given comparator.
    `<T>` | `public T` | `max(Closure closure)` Selects the maximum value found from the Iterator using the closure to determine the correct ordering.
    `<T>` | `public T` | `min()` Adds min() method to Iterator objects.
    `<T>` | `public T` | `min(Comparator<? super T> comparator)` Selects the minimum value found from the Iterator using the given comparator.
    `<T>` | `public T` | `min(Closure closure)` Selects the minimum value found from the Iterator using the closure to determine the correct ordering.
    `<T>` | `public Iterator<T>` | `plus(Iterator<T> right)` Appends two iterators.
    `<T>` | `public Iterator<T>` | `repeat(int count)` Repeat the elements from an iterator.
    `<T>` | `public Iterator<T>` | `repeat()` Repeat the elements from an iterator infinitely.
    `<T>` | `public Iterator<T>` | `reverse()` Reverses the iterator.
    `` | `public int` | `size()` Provide the standard Groovy `size()` method for `Iterator`.
    `<T>` | `public Iterator<T>` | `sort()` Sorts the given iterator items into a sorted iterator.
    `<T>` | `public Iterator<T>` | `sort(Comparator<? super T> comparator)` Sorts the given iterator items into a sorted iterator using the comparator.
    `<T>` | `public Iterator<T>` | `sort(Closure closure)` Sorts the given iterator items into a sorted iterator using the Closure to determine the correct ordering.
    `<T>` | `public Stream<T>` | `stream()` Returns a sequential Stream with the specified element(s) as its source.
    `` | `public Object` | `sum()` Sums the items from an Iterator.
    `` | `public Object` | `sum(Object initialValue)` Sums the items from an Iterator, adding the result to some initial value.
    `<T>` | `public Object` | `sum(Closure closure)` Sums the result of applying a closure to each item returned from an iterator.
    `<T>` | `public Object` | `sum(Object initialValue, Closure closure)` Sums the result of applying a closure to each item of an Iterator to some initial value.
    `<T>` | `public Iterator<T>` | `tail()` Returns the original iterator after throwing away the first element.
    `<T>` | `public Iterator<T>` | `take(int num)` Returns an iterator of up to the first `num` elements from this iterator.
    `<T>` | `public Iterator<T>` | `takeWhile(Closure condition)` Returns the longest prefix of elements in this iterator where each element passed to the given condition closure evaluates to true.
    `<T, U>` | `public Iterator<U>` | `tapEvery(int every, Closure<T> closure)` Allows the closure to be called for each (or some) elements in the iterator.
    `<T, U>` | `public Iterator<U>` | `tapEvery(Closure<T> closure)` Allows the closure to be called for each element in the iterator.
    `<T>` | `public List<T>` | `toList()` Convert an iterator to a List.
    `<T>` | `public Set<T>` | `toSet()` Convert an iterator to a Set.
    `<T>` | `public Iterator<T>` | `toSorted()` Sorts the Iterator.
    `<T>` | `public Iterator<T>` | `toSorted(Comparator<? super T> comparator)` Sorts the given iterator items using the comparator.
    `<T>` | `public Iterator<T>` | `toSorted(Closure closure)` Sorts the given iterator items into a sorted iterator using the Closure to determine the correct ordering.
    `<T>` | `public Iterator<T>` | `toUnique(Closure condition)` Returns an iterator equivalent to this iterator but with all duplicated items removed where duplicate (equal) items are deduced by calling the supplied Closure condition.
    `<T>` | `public Iterator<T>` | `toUnique(Comparator<? super T> comparator)` Returns an iterator equivalent to this iterator with all duplicated items removed by using the supplied comparator.
    `<T>` | `public Iterator<T>` | `toUnique()` Returns an iterator equivalent to this iterator with all duplicated items removed by using the natural ordering of the items.
    `<T>` | `public Iterator<T>` | `unique()` Returns an iterator equivalent to this iterator with all duplicated items removed by using Groovy's default number-aware comparator.
    `<T>` | `public Iterator<T>` | `unique(Closure condition)` Returns an iterator equivalent to this iterator but with all duplicated items removed by using a Closure to determine duplicate (equal) items.
    `<T>` | `public Iterator<T>` | `unique(Comparator<? super T> comparator)` Returns an iterator equivalent to this iterator with all duplicated items removed by using the supplied comparator.
    `<K, V>` | `public Map<K, V>` | `withCollectedKeys(Map<K, V> collector, Function<? super V, K> keyTransform)` A variant of withCollectedKeys for Iterators.
    `<K, V>` | `public Map<K, V>` | `withCollectedKeys(Function<? super V, K> keyTransform)` A variant of withCollectedKeys for Iterators.
    `<K, V>` | `public Map<K, V>` | `withCollectedValues(Map<K, V> collector, Function<? super K, V> valueTransform)` A variant of withCollectedValues for Iterators.
    `<K, V>` | `public Map<K, V>` | `withCollectedValues(Function<? super K, V> valueTransform)` A variant of withCollectedValues for Iterators.
    `<E>` | `public Iterator<Tuple2<E, Integer>>` | `withIndex()` Zips an iterator with indices in (value, index) order.
    `<E>` | `public Iterator<Tuple2<E, Integer>>` | `withIndex(int offset)` Zips an iterator with indices in (value, index) order.
    `<U, V>` | `public Iterator<Tuple2<U, V>>` | `zip(Iterator<V> other)` An iterator of all the pairs of two Iterators.
    `<U, V>` | `public Iterator<Tuple2<U, V>>` | `zipAll(Iterator<V> right, U leftDefault, V rightDefault)` An iterator of all the pairs of two Iterators with potentially different numbers of elements.

- - ### Method Detail

    - #### <T> public boolean any(Closure predicate)

      Iterates over the contents of an iterator, and checks whether a predicate is valid for at least one element.

           assert [1, 2, 3].iterator().any { it == 2 }
           assert ![1, 2, 3].iterator().any { it > 3 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if any iteration for the object matches the closure predicate
      Since:
        1.0

    - #### public boolean asBoolean()

      Coerce an iterator instance to a boolean value. An iterator is coerced to false if there are no more elements to iterate over, and to true otherwise.

      Returns:
        the boolean value
      Since:
        1.7.0

    - #### public Object average()

      Averages the items from an Iterator. This is equivalent to invoking the "plus" method on all items in the array and then dividing by the total count using the "div" method for the resulting sum. The iterator will become exhausted of elements after determining the average value. While most frequently used with aggregates of numbers, `average` will work with any class supporting `plus` and `div`, e.g.:

           class Stars {
               int numStars = 0
               String toString() {
                   '*' * numStars
               }
               Stars plus(Stars other) {
                   new Stars(numStars: numStars + other.numStars)
               }
               Stars div(Number divisor) {
                   int newSize = numStars.intdiv(divisor)
                   new Stars(numStars: newSize)
               }
           }

           def stars = [new Stars(numStars: 1), new Stars(numStars: 3)]
           assert stars*.toString() == ['*', '***']
           assert stars.average().toString() == '**'

      Returns:
        The average of all the items
      Since:
        3.0.0

    - #### <T> public Object average(Closure closure)

      Averages the result of applying a closure to each item returned from an iterator. `iter.average(closure)` is equivalent to: `iter.collect(closure).average()`. The iterator will become exhausted of elements after determining the average value.

      Example:

           assert ['to', 'from'].iterator().average{ it.size() } == 3

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
      Returns:
        The average of the values returned by applying the closure to each item from the Iterator.
      Since:
        3.0.0

    - #### <T> public BufferedIterator<T> buffered()

      Returns a `BufferedIterator` that allows examining the next element without consuming it.

           assert [1, 2, 3, 4].iterator().buffered().with { [head(), toList()] } == [1, [1, 2, 3, 4]]

      Returns:
        a BufferedIterator wrapping self
      Since:
        2.5.0

    - #### <T> public Iterator<List<T>> chop(int chopSizes)

      Chops the iterator items into pieces, returning lists with sizes corresponding to the supplied chop sizes. Using a chop size of -1 will cause that piece to contain all remaining items from the iterator.

      Example usage:

           assert (1..6).iterator().chop(1, 2, -1).toList() == [[1], [2, 3], [4, 5, 6]]

      Parameters:
        `chopSizes` - the sizes for the returned pieces
      Returns:
        an iterator of lists chopping the original iterator elements into pieces determined by chopSizes
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> chop(boolean returnEarly, int chopSizes)

      Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes. If the source iterator is exhausted early, truncated (possibly empty) pieces are returned unless returnEarly is true. Using a chop size of -1 will cause that piece to contain all remaining items from the source iterator.

      Example usage:

           assert (1..6).iterator().chop(1, 2, -1).toList() == [[1], [2, 3], [4, 5, 6]]

      Parameters:
        `chopSizes` - the sizes for the returned pieces
        `returnEarly` - as soon as the source is exhausted, ignore remaining asked for chop sizes
      Returns:
        an iterator of lists chopping the original source iterator elements into pieces determined by chopSizes
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> chop(Iterator<Integer> chopSizes)

      Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes. Using a chop size of -1 will cause that piece to contain all remaining items from the source iterator.

      Example usage:

           def stars = ['*']
               .repeat()
               .chop(Iterators.iterate(1, n -> n + 2))
               .take(10)
               *.join()
               .toList()
           def width = stars[-1].size()
           assert stars*.center(width, '.').join('\n') == '''
           .........*.........
           ........***........
           .......*****.......
           ......*******......
           .....*********.....
           ....***********....
           ...*************...
           ..***************..
           .*****************.
           *******************
           '''.trim()

      Parameters:
        `chopSizes` - the sizes for the returned pieces
      Returns:
        an iterator of lists chopping the original iterator elements into pieces determined by chopSizes
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> chop(boolean returnEarly, Iterator<Integer> chopSizes)

      Chops the source iterator elements into pieces, returning lists with sizes corresponding to the supplied chop sizes. If the source iterator is exhausted early, truncated (possibly empty) pieces are returned unless returnEarly is true. Using a chop size of -1 will cause that piece to contain all remaining items from the source iterator.

      Example usage:

           def trunk = [3, 3, 3].iterator()
           def shape = Iterators.iterate(1, n -> n + 2).take(10).plus(trunk)
           def tree = ['*']
               .repeat()
               .chop(true, shape)
               *.join()
               .toList()
           def width = tree*.size().max()
           assert tree*.center(width, '.').join('\n') == '''
           .........*.........
           ........***........
           .......*****.......
           ......*******......
           .....*********.....
           ....***********....
           ...*************...
           ..***************..
           .*****************.
           *******************
           ........***........
           ........***........
           ........***........
           '''.trim()

      Parameters:
        `chopSizes` - the sizes for the returned pieces
        `returnEarly` - as soon as the source is exhausted, ignore remaining asked for chop sizes
      Returns:
        an iterator of lists chopping the original iterator elements into pieces determined by chopSizes
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> collate(int size, int step, boolean keepRemainder)

      Collates this iterator into sub-lists of length `size` stepping through the code `step` elements for each sub-list. Any remaining elements in the iterator after the subdivision will be dropped if `keepRemainder` is false.

      Example:

           var letters = 'A'..'G'
           assert letters.iterator().collate(2, 2, false).toList() == [['A', 'B'], ['C', 'D'], ['E', 'F']]
           assert letters.iterator().collate(3, 2, true).toList() == [['A', 'B', 'C'], ['C', 'D', 'E'], ['E', 'F', 'G'], ['G']]
           assert letters.iterator().collate(2, 3, true).toList() == [['A', 'B'], ['D', 'E'], ['G']]

      Parameters:
        `size` - the length of each sub-list in the returned elements
        `step` - the number of elements to step through for each sub-list
        `keepRemainder` - if true, any remaining elements are returned as sub-lists. Otherwise they are discarded
      Returns:
        an iterator for the collated sub-lists
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> collate(int size, int step)

      Collates this iterator into sub-lists of length `size` stepping through the code `step` elements for each sub-list including any remaining elements as the last sub-list.

      Example:

           assert ('A'..'I').iterator().collate(4, 4).toList() == [['A', 'B', 'C', 'D'], ['E', 'F', 'G', 'H'], ['I']]

      Parameters:
        `size` - the length of each sub-list in the returned elements
        `step` - the number of elements to step through for each sub-list
      Returns:
        an iterator for the collated sub-lists
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> collate(int size, boolean keepRemainder)

      Collates this iterator into sub-lists of length `size`. Any remaining elements in the iterator after the subdivision will be dropped if `keepRemainder` is false.

      Example:

           assert ('A'..'I').iterator().collate(4, false).toList() == [['A', 'B', 'C', 'D'], ['E', 'F', 'G', 'H']]

      Parameters:
        `size` - the length of each sub-list in the returned elements
        `keepRemainder` - if true, any remaining elements are returned as sub-lists. Otherwise they are discarded
      Returns:
        an iterator for the collated sub-lists
      Since:
        5.0.0

    - #### <T> public Iterator<List<T>> collate(int size)

      Collates this iterator into sub-lists of length `size` including any remaining elements as the last sub-list.

      Example:

           assert ('A'..'H').iterator().collate(3).toList() == [['A', 'B', 'C'], ['D', 'E', 'F'], ['G', 'H']]

      Parameters:
        `size` - the length of each sub-list in the returned elements
      Returns:
        an iterator for the collated sub-lists
      Since:
        5.0.0

    - #### <E, T> public List<T> collect(Closure<T> transform)

      Iterates through this Iterator transforming each item into a new value using the `transform` closure, returning a list of transformed values.

      Parameters:
        `transform` - the closure used to transform each item
      Returns:
        a List of the transformed values
      Since:
        2.5.0

    - #### <E, T, C> public C collect(C collector, Closure<? extends T> transform)

      Iterates through this Iterator transforming each item into a new value using the `transform` closure and adding it to the supplied `collector`.

          assert [1,2,3].iterator().collect([]){ it * 2 } == [2,4,6]

      Parameters:
        `collector` - the Collection to which the transformed values are added
        `transform` - the closure used to transform each item
      Returns:
        the collector with all transformed values added to it
      Since:
        2.5.0

    - #### <T> public List<T> collect()

      Convert an iterator to a List. The iterator will become exhausted of elements after making this conversion. Alias for `toList`.

      Returns:
        a List of the elements from the iterator
      See Also:
        toList(Iterator)
      Since:
        5.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Closure<?> transform)

      A variant of collectEntries for Iterators.

           assert Iterators.iterate(0, Integer::next).take(4).collectEntries { n ->
               ['a'.next(n), n]
           } == [a:0, b:1, c:2, d:3]

      Parameters:
        `transform` - the closure used for transforming, which has an item from self as the parameter and should return a Map.Entry, a Map or a two-element list containing the resulting key and value
      Returns:
        a Map of the transformed entries
      See Also:
        collectEntries(Iterable, Closure)
      Since:
        1.8.7

    - #### <K, V> public Map<K, V> collectEntries()

      A variant of collectEntries for Iterators using the identity closure as the transform.

      Returns:
        a Map of the transformed entries
      See Also:
        collectEntries(Iterable)
      Since:
        1.8.7

    - #### <K, V, E> public Map<K, V> collectEntries(Map<K, V> collector, Closure<?> transform)

      A variant of collectEntries for Iterators using a supplied map as the destination of transformed entries.

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `transform` - the closure used for transforming, which has an item from self as the parameter and should return a Map.Entry, a Map or a two-element list containing the resulting key and value
      Returns:
        the collector with all transformed values added to it
      Since:
        1.8.7

    - #### <K, V, E> public Map<K, V> collectEntries(Map<K, V> collector, Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)

      A variant of collectEntries for Iterators with separate functions for transforming the keys and values. The supplied collector map is used as the destination for transformed entries.

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `keyTransform` - a function for transforming Iterator elements into keys
        `valueTransform` - a function for transforming Iterator elements into values
      Returns:
        the collector with all transformed values added to it
      Since:
        5.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)

      A variant of collectEntries for Iterators with separate functions for transforming the keys and values.

      Parameters:
        `keyTransform` - a function for transforming Iterator elements into keys
        `valueTransform` - a function for transforming Iterator elements into values
      Returns:
        a Map of the transformed entries
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> collectEntries(Map<K, V> collector)

      A variant of collectEntries for Iterators using the identity closure as the transform and a supplied map as the destination of transformed entries.

      Parameters:
        `collector` - the Map into which the transformed entries are put
      Returns:
        the collector with all transformed values added to it
      See Also:
        collectEntries(Iterable, Map)
      Since:
        1.8.7

    - #### <T, E, C> public C collectMany(C collector, Closure<? extends Collection<? extends T>> projection)

      Projects each item from a source iterator to a collection and concatenates (flattens) the resulting collections into a single list.

           def numsIter = [1, 2, 3, 4, 5, 6].iterator()
           def squaresAndCubesOfEvens = numsIter.collectMany{ if (it % 2 == 0) [it**2, it**3] }
           assert squaresAndCubesOfEvens == [4, 8, 16, 64, 36, 216]

           var letters = 'a'..'z'
           var pairs = letters.collectMany{ a ->
               letters.collectMany{ b ->
                   if (a != b) ["$a$b"]
               }
           }
           assert pairs.join(',').matches('ab,ac,ad,.*,zw,zx,zy')

      Parameters:
        `collector` - an initial collection to add the projected items to
        `projection` - a projecting Closure returning a collection of items
      Returns:
        the collector with the projected collections concatenated (flattened) to it
      See Also:
        sum(Iterator, groovy.lang.Closure)
      Since:
        1.8.1

    - #### <T, E> public List<T> collectMany(Closure<? extends Collection<? extends T>> projection)

      Projects each item from a source iterator to a collection and concatenates (flattens) the resulting collections into a single list.

           def numsIter = [1, 2, 3, 4, 5, 6].iterator()
           def squaresAndCubesOfEvens = numsIter.collectMany{ it % 2 ? [] : [it**2, it**3] }
           assert squaresAndCubesOfEvens == [4, 8, 16, 64, 36, 216]

      Parameters:
        `projection` - a projecting Closure returning a collection of items
      Returns:
        a list created from the projected collections concatenated (flattened) together
      See Also:
        collectMany(Iterator, Collection, groovy.lang.Closure)
      Since:
        1.8.1

    - #### <T, E> public List<T> collectMany()

      Flattens an iterator of collections into a single list.

           assert [1, 2].zip([10, 20]).collectMany() == [1, 10, 2, 20]

      Returns:
        a list created from the source collections concatenated (flattened) together
      See Also:
        collectMany(Iterator, groovy.lang.Closure)
      Since:
        5.0.0

    - #### <E, T> public Iterator<T> collecting(Closure<T> transform)

      Returns an iterator of transformed values from the source iterator using the `transform` closure.

           assert [1, 2, 3].repeat().collecting(Integer::next).take(6).toList() == [2, 3, 4, 2, 3, 4]
           assert Iterators.iterate('a', String::next).collecting{ (int)it - (int)'a' }.take(26).toList() == 0..25

      Parameters:
        `transform` - the closure used to transform each element
      Returns:
        an Iterator for the transformed values
      Since:
        5.0.0

    - #### <K, V, E> public Iterator<Entry<K, V>> collectingEntries(Closure<?> transform)

      Returns an iterator of transformed values from the source iterator using the `transform` closure.

           assert Iterators.iterate(0, Integer::next).take(40).collectingEntries { n ->
               var c = 'a'
               n.times{ c = c.next() }
               [c, n]
           }.take(4).collect(e -> e.key + e.value) == ['a0', 'b1', 'c2', 'd3']

      Parameters:
        `transform` - the closure used to transform each element
      Returns:
        an Iterator for the transformed values
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> collectingMany(Closure<? extends Collection<? extends T>> projection)

      Iterates through the elements produced by projecting and flattening the elements from a source iterator.

           def numsIter = [1, 2, 3, 4, 5, 6].iterator()
           def squaresAndCubesOfEvens = numsIter.collectingMany{ if (it % 2 == 0) [it**2, it**3] }.collect()
           assert squaresAndCubesOfEvens == [4, 8, 16, 64, 36, 216]

               var letters = 'a'..'z'
           var pairs = letters.iterator().collectingMany{ a ->
               letters.iterator().collectingMany{ b ->
                   if (a != b) ["$a$b"]
               }.collect()
           }.collect()
           assert pairs.join(',').matches('ab,ac,ad,.*,zw,zx,zy')

      Parameters:
        `projection` - a projecting Closure returning a collection of items
      Returns:
        an iterator of the projected collections flattened
      Since:
        5.0.0

    - #### public Number count(Object value)

      Counts the number of occurrences of the given value from the items within this Iterator. Comparison is done using Groovy's == operator (using `compareTo(value) == 0` or `equals(value)` ). The iterator will become exhausted of elements after determining the count value.

      Example usage:

           var nums = [2,4,2,1,3,2,4]
           assert nums.iterator().count(2) == 3
           assert nums.iterator().count(4) == 2

      Parameters:
        `value` - the value being searched for
      Returns:
        the number of occurrences
      Since:
        1.5.0

    - #### <T> public Number count(Closure closure)

      Counts the number of occurrences which satisfy the given closure from the items within this Iterator. The iterator will become exhausted of elements after determining the count value.

      Example usage:

           assert [2,4,2,1,3,5,2,4,3].toSet().iterator().count{ it % 2 == 0 } == 2

      Parameters:
        `closure` - a closure condition
      Returns:
        the number of occurrences
      Since:
        1.8.0

    - #### <T, E> public E count(E initialCount, Closure closure)

      Counts the number of occurrences which satisfy the given closure from the items within this Iterator, adding the count to the initial count. The iterator will become exhausted of elements after determining the count value.

      Example usage:

           assert [2,4,2,1,3,5,2,4,3].toSet().iterator().count(100){ it % 2 == 0 } == 102

      Parameters:
        `initialCount` - start counting from this value
        `closure` - a closure condition
      Returns:
        the number of occurrences
      Since:
        4.0.14

    - #### <K, E> public Map<K, Integer> countBy(Closure<K> closure)

      Sorts all iterator items into groups determined by the supplied mapping closure and counts the group size. The closure should return the key that each item should be grouped by. The returned Map will have an entry for each distinct key returned from the closure, with each value being the frequency of items occurring for that group.

      Example usage:

          assert [1,2,2,2,3].toSet().iterator().countBy{ it % 2 } == [1:2, 0:1]

      Parameters:
        `closure` - a closure mapping items to the frequency keys
      Returns:
        a new Map grouped by keys with frequency counts
      Since:
        1.8.0

    - #### <E> public Map<E, Integer> countBy()

      Creates a multiset-like map of the iterator members.

      Example usage:

          assert [1:2, 2:2, 3:1] == [1,2,1,2,3].iterator().countBy()

      Returns:
        a new Map where the keys are the set of values produced by the iterator and the values are the frequency counts
      Since:
        5.0.0

    - #### <T> public Iterator<T> drop(int num)

      Drops the given number of elements from the head of this iterator if they are available. The original iterator is stepped along by `num` elements.

           def iteratorCompare( Iterator a, List b ) {
               a.collect { it } == b
           }
           def iter = [ 1, 2, 3, 4, 5 ].listIterator()
           assert iteratorCompare( iter.drop( 0 ), [ 1, 2, 3, 4, 5 ] )
           iter = [ 1, 2, 3, 4, 5 ].listIterator()
           assert iteratorCompare( iter.drop( 2 ), [ 3, 4, 5 ] )
           iter = [ 1, 2, 3, 4, 5 ].listIterator()
           assert iteratorCompare( iter.drop( 5 ), [] )

      Parameters:
        `num` - the number of elements to drop from this iterator
      Returns:
        The iterator stepped along by `num` elements if they exist.
      Since:
        1.8.1

    - #### <T> public Iterator<T> dropRight(int num)

      Drops the given number of elements from the tail of this Iterator.

           def getObliterator() { "obliter8".iterator() }
           assert obliterator.dropRight(-1).toList() == ['o', 'b', 'l', 'i', 't', 'e', 'r', '8']
           assert obliterator.dropRight(0).toList() == ['o', 'b', 'l', 'i', 't', 'e', 'r', '8']
           assert obliterator.dropRight(1).toList() == ['o', 'b', 'l', 'i', 't', 'e', 'r']
           assert obliterator.dropRight(4).toList() == ['o', 'b', 'l', 'i']
           assert obliterator.dropRight(7).toList() == ['o']
           assert obliterator.dropRight(8).toList() == []
           assert obliterator.dropRight(9).toList() == []

      Parameters:
        `num` - the number of elements to drop
      Returns:
        an Iterator consisting of all the elements of this Iterator minus the last `num` elements, or an empty Iterator if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public Iterator<T> dropWhile(Closure<?> condition)

      Creates an Iterator that returns a suffix of the elements from an original Iterator. As many elements as possible are dropped from the front of the original Iterator such that calling the given closure condition evaluates to true when passed each of the dropped elements.

           def a = 0
           def iter = [ hasNext:{ a < 10 }, next:{ a++ } ] as Iterator
           assert [].iterator().dropWhile{ it < 3 }.toList() == []
           assert [1, 2, 3, 4, 5].iterator().dropWhile{ it < 3 }.toList() == [ 3, 4, 5 ]
           assert iter.dropWhile{ it < 5 }.toList() == [ 5, 6, 7, 8, 9 ]

      Parameters:
        `condition` - the closure that must evaluate to true to continue dropping elements
      Returns:
        the shortest suffix of elements from the given Iterator such that the given closure condition evaluates to true for each element dropped from the front of the Iterator
      Since:
        1.8.7

    - #### <T> public Iterator<T> each(Closure closure)

      Iterates through an Iterator, passing each item to the given closure.

      Parameters:
        `closure` - the closure applied on each element found
      Returns:
        the (now exhausted) self Iterator
      Since:
        2.4.0

    - #### <T> public Iterator<T> eachWithIndex(Closure closure)

      Iterates through an iterator type, passing each item and the item's index (a counter starting at zero) to the given closure.

      Parameters:
        `closure` - a Closure to operate on each item
      Returns:
        the (now exhausted) self Iterator
      Since:
        2.3.0

    - #### <T> public boolean every(Closure predicate)

      Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this iterator). A simple example for a list:

          def list = [3,4,5]
           def greaterThanTwo = list.iterator().every { it > 2 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if every iteration of the object matches the closure predicate
      Since:
        2.3.0

    - #### <T> public int findIndexOf(Closure condition)

      Iterates over the elements of an Iterator and returns the index of the first item that satisfies the condition specified by the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public int findIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an Iterator, starting from a specified startIndex, and returns the index of the first item that satisfies the condition specified by the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public Iterator<Number> findIndexValues(Closure<?> transform)

      Returns an iterator of transformed values from the source iterator using the `transform` closure.

           def letters = ('a'..'z').iterator()
           def vowels = 'aeiou'.toSet()
           assert letters.findIndexValues{ vowels.contains(it) }.toList() == [0, 4, 8, 14, 20]

      Parameters:
        `transform` - the closure used to transform each element
      Returns:
        an Iterator for the transformed values
      Since:
        5.0.0

    - #### <T> public Iterator<Number> findIndexValues(Number startIndex, Closure<?> transform)

      Returns an iterator of transformed values from the source iterator using the `transform` closure and starting with index `startIndex`.

           def letters = ('a'..'z')
           def vowels = 'aeiou'.toSet()
           assert letters.iterator().findIndexValues(0){ vowels.contains(it) }.toList() == [0, 4, 8, 14, 20]
           assert letters.iterator().findIndexValues(1){ vowels.contains(it) }.toList() == [4, 8, 14, 20]

      Parameters:
        `startIndex` - start matching from this index
        `transform` - the closure used to transform each element
      Returns:
        an Iterator for the transformed values
      Since:
        5.0.0

    - #### <T> public int findLastIndexOf(Closure condition)

      Iterates over the elements of an Iterator and returns the index of the last item that matches the condition specified in the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public int findLastIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an Iterator, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <S, T, U, V> public T findResult(U defaultResult, Closure<V> condition)

      Iterates through the Iterator calling the given closure condition for each item but stopping once the first non-null result is found and returning that result. If all are null, the defaultResult is returned.

      Examples:

           def iter = [1,2,3].iterator()
           assert "Found 2" == iter.findResult("default") { it > 1 ? "Found $it" : null }
           assert "default" == iter.findResult("default") { it > 3 ? "Found $it" : null }

      Parameters:
        `defaultResult` - an Object that should be returned if all closure results are null
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result from calling the closure, or the defaultValue
      Since:
        2.5.0

    - #### <T, U, V> public T findResult(V defaultResult)

      Iterates through the Iterator stopping once the first non-null result is found and returning that result. If all are null, the defaultResult is returned.

      Examples:

           assert [null, 1, 2].iterator().findResult('default') == 1
           assert [null, null].findResult('default') == 'default'

      Parameters:
        `defaultResult` - an Object that should be returned if all elements are null
      Returns:
        the first non-null result from the iterator, or the defaultValue
      Since:
        4.0.9

    - #### <T, U> public T findResult(Closure<T> condition)

      Iterates through the Iterator calling the given closure condition for each item but stopping once the first non-null result is found and returning that result. If all results are null, null is returned.

      Parameters:
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result from calling the closure, or null
      Since:
        2.5.0

    - #### <T> public T findResult()

      Iterates through the Iterator stopping once the first non-null result is found and returning that result. If all results are null, null is returned.

      Returns:
        the first non-null result from the iterator, or null
      Since:
        4.0.9

    - #### <T, U> public Collection<T> findResults(Closure<T> filteringTransform)

      Iterates through the Iterator transforming items using the supplied closure and collecting any non-null results.

      Parameters:
        `filteringTransform` - a Closure that should return either a non-null transformed value or null for items which should be discarded
      Returns:
        the list of non-null transformed values
      Since:
        2.5.0

    - #### <T> public Collection<T> findResults()

      Iterates through the Iterator collecting any non-null results.

      Returns:
        the list of non-null values
      Since:
        4.0.9

    - #### <T> public Iterator<T> findingAll(Closure<?> transform)

      Lazily finds all items matching the closure condition.

           def letters = Iterators.iterate('A', String::next).take(26).plus(Iterators.iterate('a', String::next).take(26))
           assert letters.findingAll{ it.toUpperCase() < 'D' }.toList() == ['A', 'B', 'C', 'a', 'b', 'c']

      Parameters:
        `transform` - the closure used to select elements
      Returns:
        an Iterator returning the selected elements
      Since:
        5.0.0

    - #### <T, U> public Iterator<T> findingResults(Closure<T> filteringTransform)

      Iterates through the Iterator transforming items using the supplied closure and finding any non-null results.

      Example:

           def vowels = [a:1, e:5, i:9, o:15, u:21]
           assert Iterators.iterate('a', n -> ++n).findingResults{ vowels[it] }.take(3).toList() == [1, 5, 9]

      Parameters:
        `filteringTransform` - a Closure that should return either a non-null transformed value or null for items which should be discarded
      Returns:
        an iterator for the non-null transformed values
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> flatten()

      Flatten an Iterator. This Iterator and any nested arrays, iterators or collections have their contents (recursively) added to the elements of the new iterator. Non-empty optionals are also flattened.

      Example:

           var items = [1..2, [3, [4]], Optional.of(5)]
           assert items.iterator().flatten().toList() == [1, 2, 3, 4, 5]

      Returns:
        an iterator of the flattened elements
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> flatten(boolean flattenOptionals)

      Flatten an Iterator. This Iterator and any nested arrays, iterators or collections have their contents (recursively) added to the elements of the new iterator. If flattenOptionals is true, the non-empty optionals are also flattened.

      Example:

           var items = [1..2, [3, [4]], Optional.of(5), Optional.empty()]
           assert items.iterator().flatten(true).toList() == [1, 2, 3, 4, 5]
           assert items.iterator().flatten(false).toList() == [1, 2, 3, 4, Optional.of(5), Optional.empty()]

      Parameters:
        `flattenOptionals` - whether to treat an Optional as a container to flatten
      Returns:
        an iterator of the flattened elements
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> flatten(Closure<?> flattenUsing)

      Flatten an Iterator. This Iterator and any nested arrays, iterators, collections, and potentially Optional elements have their contents (recursively) added to the elements for a new iterator. Non-container elements are leaf elements.

      Example:

           assert [1..2, [3, [4]]].iterator().flatten(n -> n + 5).toList() == 6..9

      Parameters:
        `flattenUsing` - a closure to determine how to flatten leaf elements
      Returns:
        an iterator of the flattened items
      See Also:
        flatten(Iterable, Closure)
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> flatten(boolean flattenOptionals, Closure<?> flattenUsing)

      Flatten an Iterator. This Iterator and any nested arrays, iterators, collections, and potentially Optional elements have their contents (recursively) added to the elements for a new iterator. Non-container elements are leaf elements.

      Parameters:
        `flattenOptionals` - whether to treat an Optional as a container to flatten or a leaf
        `flattenUsing` - a closure to determine how to flatten leaf elements
      Returns:
        an iterator of the flattened items
      See Also:
        flatten(Iterable, boolean, Closure)
      Since:
        5.0.0

    - #### <T, E> public Iterator<T> flattenMany(boolean flattenOptionals, Closure<?> flattenUsing)

      Flatten the elements from an Iterator. This iterator and any nested arrays, collections, iterators, or optionals have their contents (recursively) added to the elements for the resulting iterator. A transform is applied to any leaf nodes before further flattening.

      Parameters:
        `flattenOptionals` - whether non-present Optional values are removed
        `flattenUsing` - a transform applied to any leaf elements
      Returns:
        a flattened Collection
      See Also:
        flattenMany(Iterable, Closure)
      Since:
        5.0.0

    - #### <T> public T getAt(int idx)

      Support the subscript operator for an Iterator. The iterator will be partially exhausted up until the idx entry after returning if a +ve or 0 idx is used, or fully exhausted if a -ve idx is used or no corresponding entry was found. Typical usage:

           def iter = [2, "a", 5.3].iterator()
           assert iter[1] == "a"

      A more elaborate example:

           def items = [2, "a", 5.3]
           def iter = items.iterator()
           assert iter[-1] == 5.3
           // iter exhausted, so reset
           iter = items.iterator()
           assert iter[1] == "a"
           // iter partially exhausted so now idx starts after "a"
           assert iter[0] == 5.3

      Parameters:
        `idx` - an index value (-self.size() <= idx < self.size())
      Returns:
        the value at the given index (after normalisation) or null if no corresponding value was found
      Since:
        1.7.2

    - #### <T> public Iterator<T> grepping(Object filter)

      Lazily returns an Iterator of items matching the given filter - calling the `Object.isCase` method used by switch statements. This method can be used with different kinds of filters like regular expressions, classes, ranges etc.

           def iter = [1, 'a', 'aa', 2, 'bc', 3, 4.5].iterator()
           assert iter.grepping(Number).toList() == [1, 2, 3, 4.5]

      Parameters:
        `filter` - the filter to perform on each element (using the Object.isCase method)
      Returns:
        an Iterator returning the filtered elements
      Since:
        6.0.0

    - #### <T> public Iterator<T> grepping()

      Lazily returns an Iterator of elements which satisfy Groovy truth. Equivalent to calling Iterator.grepping with the IDENTITY Closure.

           def iter = [1, 2, 0, false, true, '', 'foo', [], [4, 5], null].iterator()
           assert iter.grepping().toList() == [1, 2, true, 'foo', [4, 5]]

      Returns:
        an Iterator of elements satisfying Groovy truth
      See Also:
        Closure.IDENTITY
      Since:
        6.0.0

    - #### <E> public Iterator<Tuple2<Integer, E>> indexed()

      Zips an iterator with indices in (index, value) order.

      Example usage:

           assert [[0, "a"], [1, "b"]] == ["a", "b"].iterator().indexed().collect{ tuple -> [tuple.first, tuple.second] }
           assert ["0: a", "1: b"] == ["a", "b"].iterator().indexed().collect { idx, str -> "$idx: $str" }.toList()

      Returns:
        a zipped iterator with indices
      See Also:
        withIndex(Iterator)
      Since:
        2.4.0

    - #### <E> public Iterator<Tuple2<Integer, E>> indexed(int offset)

      Zips an iterator with indices in (index, value) order.

      Example usage:

           assert [[5, "a"], [6, "b"]] == ["a", "b"].iterator().indexed(5).toList()
           assert ["a: 1", "b: 2"] == ["a", "b"].iterator().indexed(1).collect { idx, str -> "$str: $idx" }.toList()

      Parameters:
        `offset` - an index to start from
      Returns:
        a zipped iterator with indices
      See Also:
        withIndex(Iterator, int)
      Since:
        2.4.0

    - #### <T> public Iterator<T> init()

      Returns an Iterator containing all the items from this iterator except the last one.

           def iter = [3, 4, 2].listIterator()
           def result = iter.init()
           assert result.toList() == [3, 4]

      throws:
        NoSuchElementException if you try to access init() for an exhausted/empty Iterator
      Returns:
        an Iterator without the last element from the original Iterator
      Since:
        2.4.0

    - #### <E, T, U, V> public T inject(U initialValue, Closure<V> closure)

      Iterates through the given iterator, passing in the initial value to the closure along with the first item. The result is passed back (injected) into the closure along with the second item. The new result is injected back into the closure along with the third item and so on until further iteration is not possible.

      Also known as `foldLeft` or `reduce` in functional parlance.

      Parameters:
        `initialValue` - some initial value
        `closure` - a closure
      Returns:
        the result of the last closure call
      Since:
        1.5.0

    - #### <E, T, U, V> public Iterator<T> injectAll(U initialValue, Closure<V> closure)

      Iterates through the given iterator, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.

      Example:

           assert (1..3)
               .iterator()
               .injectAll(''){ carry, next -> carry + next }
               .toList() == ['1', '12', '123']

      See Also:
        injectAll(Iterable, Object, Closure)
      Since:
        5.0.0

    - #### <E, T, V> public Iterator<T> injectAll(Closure<V> closure)

      Iterates through the given iterator, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.

      Example:

           assert (1..5).iterator().injectAll(Integer::plus).toList() == [3, 6, 10, 15]

      Since:
        5.0.0

    - #### <T, U, V> public Iterator<T> interleave(Iterator<V> other)

      An iterator of the elements from two Iterators interleaved. If the sources are of different sizes, the result will have twice the size of the shorter one.

      Example:

           def items = (1..4).iterator()
           def other = [10, 20].iterator()
           assert [1, 10, 2, 20] == items.interleave(other).toList()

      Parameters:
        `other` - another Iterator
      Returns:
        an iterator of all the pairs from self and other
      Since:
        5.0.0

    - #### <T, U, V> public Iterator<T> interleave(Iterator<V> other, boolean includeRemainder)

      An iterator of the elements from two Iterators interleaved. If the sources are of different sizes, and `includeRemainder` is true, the extra elements from the longer source will be appended after interleaving.

      Example:

           def items = (1..4).iterator()
           def other = [10, 20].iterator()
           assert [1, 10, 2, 20, 3, 4] == items.interleave(other, true).toList()

      When `includeRemainder` is false, this is equivalent to `zip` then `collectMany`.

      Parameters:
        `other` - an Iterable
        `includeRemainder` - whether to process extra elements if the operands are of different sizes
      Returns:
        an iterator of all the pairs from self and other
      Since:
        5.0.0

    - #### <T> public boolean isSorted()

      Determines if the Iterator elements are sorted. Assumes the elements are comparable and uses a NumberAwareComparator to determine the order.

      The iterator will be exhausted of elements after determining the sorted status.

      Returns:
        true if the elements are sorted in non-descending order
      See Also:
        isSorted(Iterator, Comparator)
      Since:
        6.0.0

    - #### <T> public boolean isSorted(Comparator<? super T> comparator)

      Determines if the Iterator elements are sorted according to the given Comparator. This is efficient Ã¢â‚¬â€? it checks adjacent pairs and short-circuits on the first out-of-order pair. The iterator will be exhausted only if the elements are sorted.

      Parameters:
        `comparator` - a Comparator used for the comparison
      Returns:
        true if the elements are sorted according to the comparator
      Since:
        6.0.0

    - #### <T> public boolean isSorted(Closure closure)

      Determines if the Iterator elements are sorted using the given Closure to determine order.

      If the Closure has two parameters it is used like a traditional Comparator. Otherwise, the Closure is assumed to take a single parameter and return a Comparable which is then used for further comparison.

      The iterator will be exhausted of elements after determining the sorted status.

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine the ordering
      Returns:
        true if the elements are sorted according to the closure
      See Also:
        isSorted(Iterator, Comparator)
      Since:
        6.0.0

    - #### <T> public Iterator<T> iterator()

      Supports 'duck-typing' when trying to get an Iterator for each element of a Collection, some of which may already be an Iterator.

      Returns:
        the Iterator itself
      Since:
        1.5.0

    - #### public String join()

      Concatenates the `toString()` representation of each item from the Iterator. The iterator will be exhausted of elements.

      Returns:
        the joined String
      Since:
        5.0.0

    - #### public String join(String separator)

      Concatenates the `toString()` representation of each item from the Iterator, with the given String as a separator between each item. The iterator will become exhausted of elements after producing the resulting conjoined value.

      Parameters:
        `separator` - a String separator
      Returns:
        the joined String
      Since:
        1.5.5

    - #### <T> public T max()

      Adds max() method to Iterator objects. The iterator will become exhausted of elements after determining the maximum value.

      Returns:
        the maximum value
      Since:
        1.5.5

    - #### <T> public T max(Comparator<? super T> comparator)

      Selects the maximum value found from the Iterator using the given comparator.

      Parameters:
        `comparator` - a Comparator
      Returns:
        the maximum value
      Since:
        1.5.5

    - #### <T> public T max(Closure closure)

      Selects the maximum value found from the Iterator using the closure to determine the correct ordering. The iterator will become exhausted of elements after this operation.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

      Parameters:
        `closure` - a Closure used to determine the correct ordering
      Returns:
        the maximum value
      Since:
        1.5.5

    - #### <T> public T min()

      Adds min() method to Iterator objects. The iterator will become exhausted of elements after determining the minimum value.

      Returns:
        the minimum value
      See Also:
        min(Iterable)
      Since:
        1.5.5

    - #### <T> public T min(Comparator<? super T> comparator)

      Selects the minimum value found from the Iterator using the given comparator.

      Parameters:
        `comparator` - a Comparator
      Returns:
        the minimum value
      Since:
        1.5.5

    - #### <T> public T min(Closure closure)

      Selects the minimum value found from the Iterator using the closure to determine the correct ordering. The iterator will become exhausted of elements after this operation.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

      Parameters:
        `closure` - a Closure used to determine the correct ordering
      Returns:
        the minimum value
      Since:
        1.5.5

    - #### <T> public Iterator<T> plus(Iterator<T> right)

      Appends two iterators.

           assert [1, 2].iterator().plus([3, 4].iterator()).toList() == 1..4

      Parameters:
        `right` - an Iterator
      Returns:
        an iterator of all the items from the first then second iterator
      Since:
        5.0.0

    - #### <T> public Iterator<T> repeat(int count)

      Repeat the elements from an iterator.

           assert ['a', 42].iterator().repeat(2).toList() == ['a', 42, 'a', 42]

      Parameters:
        `count` - the (non-negative) number of times to repeat
      Returns:
        an iterator containing the repeated elements
      Since:
        5.0.0

    - #### <T> public Iterator<T> repeat()

      Repeat the elements from an iterator infinitely.

           assert ['a', 42].iterator().repeat().take(5).toList() == ['a', 42, 'a', 42, 'a']

      Returns:
        an iterator containing the (infinite) repeated elements
      Since:
        5.0.0

    - #### <T> public Iterator<T> reverse()

      Reverses the iterator. The original iterator will become exhausted of elements after determining the reversed values. A new iterator for iterating through the reversed values is returned.

      Returns:
        a reversed Iterator
      Since:
        1.5.5

    - #### public int size()

      Provide the standard Groovy `size()` method for `Iterator`. The iterator will become exhausted of elements after determining the size value.

      Returns:
        the length of the Iterator
      Since:
        1.5.5

    - #### <T> public Iterator<T> sort()

      Sorts the given iterator items into a sorted iterator. The items are assumed to be comparable. The original iterator will become exhausted of elements after completing this method call. A new iterator is produced that traverses the items in sorted order.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Returns:
        the sorted items as an Iterator
      Since:
        1.5.5

    - #### <T> public Iterator<T> sort(Comparator<? super T> comparator)

      Sorts the given iterator items into a sorted iterator using the comparator. The original iterator will become exhausted of elements after completing this method call. A new iterator is produced that traverses the items in sorted order.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Parameters:
        `comparator` - a Comparator used for comparing items
      Returns:
        the sorted items as an Iterator
      Since:
        1.5.5

    - #### <T> public Iterator<T> sort(Closure closure)

      Sorts the given iterator items into a sorted iterator using the Closure to determine the correct ordering. The original iterator will be fully processed after the method call.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Parameters:
        `closure` - a Closure used to determine the correct ordering
      Returns:
        the sorted items as an Iterator
      Since:
        1.5.5

    - #### <T> public Stream<T> stream()

      Returns a sequential Stream with the specified element(s) as its source.

           [].iterator().stream().toList().isEmpty()
           ['one', 'two'].iterator().stream().toList() == ['one', 'two']

      Since:
        3.0.0

    - #### public Object sum()

      Sums the items from an Iterator. This is equivalent to invoking the "plus" method on all items from the Iterator. The iterator will become exhausted of elements after determining the sum value.

      Returns:
        The sum of all the items
      Since:
        1.5.5

    - #### public Object sum(Object initialValue)

      Sums the items from an Iterator, adding the result to some initial value. This is equivalent to invoking the "plus" method on all items from the Iterator. The iterator will become exhausted of elements after determining the sum value.

      Parameters:
        `initialValue` - the items in the collection will be summed to this initial value
      Returns:
        The sum of all the items
      Since:
        1.5.5

    - #### <T> public Object sum(Closure closure)

      Sums the result of applying a closure to each item returned from an iterator. `iter.sum(closure)` is equivalent to: `iter.collect(closure).sum()`. The iterator will become exhausted of elements after determining the sum value.

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
      Returns:
        The sum of the values returned by applying the closure to each item from the Iterator.
      Since:
        1.7.1

    - #### <T> public Object sum(Object initialValue, Closure closure)

      Sums the result of applying a closure to each item of an Iterator to some initial value. `iter.sum(initVal, closure)` is equivalent to: `iter.collect(closure).sum(initVal)`. The iterator will become exhausted of elements after determining the sum value.

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
        `initialValue` - the closure results will be summed to this initial value
      Returns:
        The sum of the values returned by applying the closure to each item from the Iterator.
      Since:
        1.7.1

    - #### <T> public Iterator<T> tail()

      Returns the original iterator after throwing away the first element.

      throws:
        NoSuchElementException if you try to access tail() for an exhausted/empty Iterator
      Returns:
        the iterator without its first element
      Since:
        1.8.1

    - #### <T> public Iterator<T> take(int num)

      Returns an iterator of up to the first `num` elements from this iterator. The original iterator is stepped along by `num` elements.

           def a = 0
           def iter = [ hasNext:{ true }, next:{ a++ } ] as Iterator
           def iteratorCompare( Iterator a, List b ) {
               a.collect { it } == b
           }
           assert iteratorCompare( iter.take( 0 ), [] )
           assert iteratorCompare( iter.take( 2 ), [ 0, 1 ] )
           assert iteratorCompare( iter.take( 5 ), [ 2, 3, 4, 5, 6 ] )

      Parameters:
        `num` - the number of elements to take from this iterator
      Returns:
        an iterator consisting of up to the first `num` elements of this iterator.
      Since:
        1.8.1

    - #### <T> public Iterator<T> takeWhile(Closure condition)

      Returns the longest prefix of elements in this iterator where each element passed to the given condition closure evaluates to true.

           def a = 0
           def iter = [ hasNext:{ true }, next:{ a++ } ] as Iterator

           assert [].iterator().takeWhile{ it < 3 }.toList() == []
           assert [1, 2, 3, 4, 5].iterator().takeWhile{ it < 3 }.toList() == [ 1, 2 ]
           assert iter.takeWhile{ it < 5 }.toList() == [ 0, 1, 2, 3, 4 ]

      Parameters:
        `condition` - the closure that must evaluate to true to continue taking elements
      Returns:
        a prefix of elements in the given iterator where each element passed to the given closure evaluates to true
      Since:
        1.8.7

    - #### <T, U> public Iterator<U> tapEvery(int every, Closure<T> closure)

      Allows the closure to be called for each (or some) elements in the iterator.

      Example:

           def items = (1..9).iterator()
           def collected = []
           assert items.tapEvery(3) { collected << it }.toList() == 1..9
           assert collected == [1, 4, 7]

      Parameters:
        `closure` - the closure to call
        `every` - call the closure every this many elements
      Returns:
        an Iterator for the original elements
      Since:
        5.0.0

    - #### <T, U> public Iterator<U> tapEvery(Closure<T> closure)

      Allows the closure to be called for each element in the iterator.

      Example:

           def items = (1..9).iterator()
           def collected = []
           assert items.tapEvery { collected << it }.toList() == 1..9
           assert collected == 1..9

           var nums = []
           assert [
               [x: 3, y: 4],
               [x: 5, y: 12],
               [x: 8, y: 15],
               [x: 7, y: 24]
           ].iterator().tapEvery {
               nums << Math.sqrt(x ** 2 + y ** 2).intValue()
           }*.x == [3, 5, 8, 7]
           assert nums == [5, 13, 17, 25]

      Parameters:
        `closure` - the closure to call
      Returns:
        an Iterator for the original elements
      Since:
        5.0.0

    - #### <T> public List<T> toList()

      Convert an iterator to a List. The iterator will become exhausted of elements after making this conversion.

      Returns:
        a List of the elements from the iterator
      Since:
        1.5.0

    - #### <T> public Set<T> toSet()

      Convert an iterator to a Set. The iterator will become exhausted of elements after making this conversion.

      Returns:
        a Set
      Since:
        1.8.0

    - #### <T> public Iterator<T> toSorted()

      Sorts the Iterator. Assumes that the Iterator elements are comparable and uses a NumberAwareComparator to determine the resulting order. `NumberAwareComparator` has special treatment for numbers but otherwise uses the natural ordering of the Iterator elements. A new iterator is produced that traverses the items in sorted order.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Returns:
        the sorted items as an Iterator
      See Also:
        toSorted(Iterator, Comparator)
      Since:
        2.4.0

    - #### <T> public Iterator<T> toSorted(Comparator<? super T> comparator)

      Sorts the given iterator items using the comparator. The original iterator will become exhausted of elements after completing this method call. A new iterator is produced that traverses the items in sorted order.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Parameters:
        `comparator` - a Comparator used for comparing items
      Returns:
        the sorted items as an Iterator
      Since:
        2.4.0

    - #### <T> public Iterator<T> toSorted(Closure closure)

      Sorts the given iterator items into a sorted iterator using the Closure to determine the correct ordering. The original iterator will be fully processed after the method call.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

      The iterator is exhausted before elements are produced, so this method isn't suitable for use with infinite iterators.

      Parameters:
        `closure` - a Closure used to determine the correct ordering
      Returns:
        the sorted items as an Iterator
      See Also:
        toSorted(Iterator, Comparator)
      Since:
        2.4.0

    - #### <T> public Iterator<T> toUnique(Closure condition)

      Returns an iterator equivalent to this iterator but with all duplicated items removed where duplicate (equal) items are deduced by calling the supplied Closure condition.

      If the supplied Closure takes a single parameter, the argument passed will be each element, and the closure should return a value used for comparison (either using Comparable.compareTo or Object.equals). If the closure takes two parameters, two items from the Iterator will be passed as arguments, and the closure should return an int value (with 0 indicating the items are not unique).

           def items = "Hello".toList() + [null, null] + "there".toList()
           def toLower = { it == null ? null : it.toLowerCase() }
           def noDups = items.iterator().toUnique(toLower).toList()
           assert noDups == ['H', 'e', 'l', 'o', null, 't', 'r']

          assert [1,4] == [1,3,4,5].toUnique { it % 2 }

          assert [2,3,4] == [2,3,3,4].toUnique { a, b -> a <=> b }

      Parameters:
        `condition` - a Closure used to determine unique items
      Returns:
        an Iterator with no duplicate items
      Since:
        2.4.0

    - #### <T> public Iterator<T> toUnique(Comparator<? super T> comparator)

      Returns an iterator equivalent to this iterator with all duplicated items removed by using the supplied comparator.

      Parameters:
        `comparator` - a Comparator used to determine unique (equal) items If `null`, the Comparable natural ordering of the elements will be used.
      Returns:
        an Iterator with no duplicate items
      Since:
        2.4.0

    - #### <T> public Iterator<T> toUnique()

      Returns an iterator equivalent to this iterator with all duplicated items removed by using the natural ordering of the items.

      Returns:
        an Iterator with no duplicate items
      Since:
        2.4.0

    - #### <T> public Iterator<T> unique()

      Returns an iterator equivalent to this iterator with all duplicated items removed by using Groovy's default number-aware comparator. The original iterator will become exhausted of elements after determining the unique values. A new iterator for the unique values will be returned.

      Returns:
        a new Iterator of the unique items from the original iterator
      Since:
        1.5.5

    - #### <T> public Iterator<T> unique(Closure condition)

      Returns an iterator equivalent to this iterator but with all duplicated items removed by using a Closure to determine duplicate (equal) items. The original iterator will be fully processed after the call.

      If the closure takes a single parameter, the argument passed will be each element, and the closure should return a value used for comparison (either using Comparable.compareTo or Object.equals). If the closure takes two parameters, two items from the Iterator will be passed as arguments, and the closure should return an int value (with 0 indicating the items are not unique).

      Parameters:
        `condition` - a Closure used to determine unique items
      Returns:
        the modified Iterator
      Since:
        1.5.5

    - #### <T> public Iterator<T> unique(Comparator<? super T> comparator)

      Returns an iterator equivalent to this iterator with all duplicated items removed by using the supplied comparator. The original iterator will be exhausted upon returning.

      Parameters:
        `comparator` - a Comparator
      Returns:
        the modified Iterator
      Since:
        1.5.5

    - #### <K, V> public Map<K, V> withCollectedKeys(Map<K, V> collector, Function<? super V, K> keyTransform)

      A variant of withCollectedKeys for Iterators.

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `keyTransform` - a function for transforming Iterator elements into values
      Returns:
        the collector with all transformed values added to it
      See Also:
        withCollectedKeys(Iterable, Map, Function)
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedKeys(Function<? super V, K> keyTransform)

      A variant of withCollectedKeys for Iterators.

      Parameters:
        `keyTransform` - a function for transforming Iterator elements into values
      Returns:
        a Map of the transformed entries
      See Also:
        withCollectedKeys(Iterable, Function)
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedValues(Map<K, V> collector, Function<? super K, V> valueTransform)

      A variant of withCollectedValues for Iterators.

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `valueTransform` - a function for transforming Iterator elements into values
      Returns:
        the collector with all transformed values added to it
      See Also:
        withCollectedValues(Iterable, Map, Function)
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedValues(Function<? super K, V> valueTransform)

      A variant of withCollectedValues for Iterators.

      Parameters:
        `valueTransform` - a function for transforming Iterator elements into values
      Returns:
        a Map of the transformed entries
      See Also:
        withCollectedValues(Iterable, Function)
      Since:
        5.0.0

    - #### <E> public Iterator<Tuple2<E, Integer>> withIndex()

      Zips an iterator with indices in (value, index) order.

      Example usage:

           assert [["a", 0], ["b", 1]] == ["a", "b"].iterator().withIndex().toList()
           assert ["0: a", "1: b"] == ["a", "b"].iterator().withIndex().collect { str, idx -> "$idx: $str" }.toList()

      Returns:
        a zipped iterator with indices
      See Also:
        indexed(Iterator)
      Since:
        2.4.0

    - #### <E> public Iterator<Tuple2<E, Integer>> withIndex(int offset)

      Zips an iterator with indices in (value, index) order.

      Example usage:

           assert [["a", 5], ["b", 6]] == ["a", "b"].iterator().withIndex(5).toList()
           assert ["1: a", "2: b"] == ["a", "b"].iterator().withIndex(1).collect { str, idx -> "$idx: $str" }.toList()

      Parameters:
        `offset` - an index to start from
      Returns:
        a zipped iterator with indices
      See Also:
        indexed(Iterator, int)
      Since:
        2.4.0

    - #### <U, V> public Iterator<Tuple2<U, V>> zip(Iterator<V> other)

      An iterator of all the pairs of two Iterators. If the iterators are of different sizes, the result will have the same size as the shorter one.

      Example:

           def small = [1, 2, 3].iterator()
           def large = [100, 200, 300].iterator()
           assert [101, 202, 303] == small.zip(large).collect{ a, b -> a + b }
           assert [small.toList(), large.toList()].transpose() == small.zip(large).toList()

      Parameters:
        `other` - another Iterator
      Returns:
        an iterator of all the pairs from self and other
      Since:
        5.0.0

    - #### <U, V> public Iterator<Tuple2<U, V>> zipAll(Iterator<V> right, U leftDefault, V rightDefault)

      An iterator of all the pairs of two Iterators with potentially different numbers of elements. If the iterables are of different sizes, the result will have the same size as the longer one with values completed using the provided default.

      Example:

           def ab = ['a', 'b'].iterator()
           def abcd = ('a'..'d').iterator()
           def nums = (1..3).iterator()
           assert ['a1', 'b2', 'unknown3'] == ab.zipAll(nums, 'unknown', 0).collect{ a, b -> a + b }
           nums = (1..3).iterator()
           assert ['a1', 'b2', 'c3', 'd0'] == abcd.zipAll(nums, 'unknown', 0).collect{ a, b -> a + b }

      Parameters:
        `right` - another Iterator
      Returns:
        an iterator of all the pairs from left and right
      Since:
        5.0.0