Iterator (Groovy JDK enhancements)

Package: java.util

## Interface Iterator

- - ### Methods Summary

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

- - ### Methods Detail

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

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

    - #### public BufferedIterator 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

    - #### public Iterator 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

    - #### public Iterator chop(boolean returnEarly, Iterator 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

    - #### public Iterator 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

    - #### public Iterator chop(Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public List 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
      Since:
        5.0.0
      See Also:
        Iterator#toList()

    - #### public List collect(Closure 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

    - #### public Object collect(Object collector, Closure 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

    - #### public Map collectEntries()

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

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

    - #### public Map 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
      Since:
        1.8.7
      See Also:
        Iterable#collectEntries(Closure)

    - #### public Map collectEntries(Map 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
      Since:
        1.8.7
      See Also:
        Iterable#collectEntries(Map)

    - #### public Map collectEntries(Map 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

    - #### public Map collectEntries(Map collector, Function keyTransform, Function 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

    - #### public Map collectEntries(Function keyTransform, Function 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

    - #### public List 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
      Since:
        5.0.0
      See Also:
        Iterator#collectMany(groovy.lang.Closure)

    - #### public List collectMany(Closure 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
      Since:
        1.8.1
      See Also:
        Iterator#collectMany(Collection, groovy.lang.Closure)

    - #### public Object collectMany(Object collector, Closure 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
      Since:
        1.8.1
      See Also:
        Iterator#sum(groovy.lang.Closure)

    - #### public Iterator collecting(Closure 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

    - #### public Iterator 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

    - #### public Iterator collectingMany(Closure 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(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

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

    - #### public Object count(Object 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

    - #### public Map 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

    - #### public Map countBy(Closure 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

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

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

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

    - #### public Iterator 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

    - #### public Iterator 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

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

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

    - #### public Object 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

    - #### public Object findResult(Closure 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

    - #### public Object findResult(Object 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

    - #### public Object findResult(Object defaultResult, Closure 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

    - #### public Collection findResults()

      Iterates through the Iterator collecting any non-null results.

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

    - #### public Collection findResults(Closure 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

    - #### public Iterator 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

    - #### public Iterator findingResults(Closure 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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
      Since:
        5.0.0
      See Also:
        Iterable#flatten(boolean, Closure)

    - #### public Iterator 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
      Since:
        5.0.0
      See Also:
        Iterable#flatten(Closure)

    - #### public Iterator 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
      Since:
        5.0.0
      See Also:
        Iterable#flattenMany(Closure)

    - #### public Object 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

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#withIndex()

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#withIndex(int)

    - #### public Iterator 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]

      Returns:
        an Iterator without the last element from the original Iterator
      Since:
        2.4.0

    - #### public Object inject(Object initialValue, Closure 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

    - #### public Iterator injectAll(Closure 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]

      Parameters:
      Since:
        5.0.0

    - #### public Iterator injectAll(Object initialValue, Closure 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']

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

    - #### public Iterator interleave(Iterator 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

    - #### public Iterator interleave(Iterator 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

    - #### public Iterator 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

    - #### public Object 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

    - #### public Object 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

    - #### public Object max(Comparator 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

    - #### public Object min()

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

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

    - #### public Object 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

    - #### public Object min(Comparator 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

    - #### public Iterator plus(Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator sort(Comparator 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

    - #### public Stream 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(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

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

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

    - #### public Iterator tail()

      Returns the original iterator after throwing away the first element.

      Returns:
        the iterator without its first element
      Since:
        1.8.1

    - #### public Iterator 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

    - #### public Iterator 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

    - #### public Iterator tapEvery(Closure 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

    - #### public Iterator tapEvery(int every, Closure 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

    - #### public List 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

    - #### public Set 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

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#toSorted(Comparator)

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#toSorted(Comparator)

    - #### public Iterator toSorted(Comparator 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

    - #### public Iterator 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

    - #### public Iterator 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(java.lang.Object) or Object#equals(java.lang.Object)). 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

    - #### public Iterator toUnique(Comparator 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

    - #### public Iterator 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

    - #### public Iterator 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(java.lang.Object) or Object#equals(java.lang.Object)). 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

    - #### public Iterator unique(Comparator 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

    - #### public Map withCollectedKeys(Map collector, Function 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
      Since:
        5.0.0
      See Also:
        Iterable#withCollectedKeys(Map, Function)

    - #### public Map withCollectedKeys(Function keyTransform)

      A variant of withCollectedKeys for Iterators.

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

    - #### public Map withCollectedValues(Map collector, Function 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
      Since:
        5.0.0
      See Also:
        Iterable#withCollectedValues(Map, Function)

    - #### public Map withCollectedValues(Function valueTransform)

      A variant of withCollectedValues for Iterators.

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

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#indexed()

    - #### public Iterator 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
      Since:
        2.4.0
      See Also:
        Iterator#indexed(int)

    - #### public Iterator zip(Iterator 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

    - #### public Iterator zipAll(Iterator right, Object leftDefault, Object 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