Iterator (Groovy JDK enhancements)

Methods Summary

Methods
Return type	Name and parameters
`boolean`	`any(Closure closure)` 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.
`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.
`List`	`collectMany(Closure projection)` Projects each item from a source iterator to a collection and concatenates (flattens) the resulting collections into a single list.
`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.
`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`	`dropWhile(Closure condition)` Creates an Iterator that returns a suffix of the elements from an original Iterator.
`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 closure)` Used to determine if the given predicate closure is valid (i.e.
`Object`	`getAt(int idx)` Support the subscript operator for an Iterator.
`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`	`iterator()` An identity function for iterators, supporting 'duck-typing' when trying to get an iterator for each object within a collection, some of which may already be iterators.
`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`	`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.
`Object`	`sum()` Sums the items from an Iterator.
`Object`	`sum(Closure closure)` Sums the result of apply 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`	`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.
`List`	`toList()` Convert an iterator to a List.
`Set`	`toSet()` Convert an iterator to a Set.
`Iterator`	`unique()` Returns an iterator equivalent to this iterator all duplicated items removed by using the default comparator.
`Iterator`	`unique(Closure closure)` 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.

- Methods Detail
  - public boolean any(Closure closure)
    
    Iterates over the contents of an iterator, and checks whether a predicate is valid for at least one element.
    
    Parameters:
    
    closure - 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 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.
    
    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 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#sum(groovy.lang.Closure)
  - 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.
    
    Parameters:
    
    value - the value being searched for
    
    Returns:
    
    the number of occurrences
    
    Since:
    
    1.5.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
    
    See Also:
    
    Collection#countBy(Closure)
  - 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 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 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 self Iterable
    
    Since:
    
    2.3.0
  - public boolean every(Closure closure)
    
    Used to determine if the given predicate closure is valid (i.e.&nsbp;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:
    
    closure - the closure predicate used for matching
    
    Returns:
    
    true if every iteration of the object matches the closure predicate
    
    Since:
    
    2.3.0
  - 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 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 the Iterator has been expired of values. Also known as foldLeft in functional parlance.
    
    Parameters:
    
    initialValue - some initial value
    
    closure - a closure
    
    Returns:
    
    the result of the last closure call
    
    Since:
    
    1.5.0
    
    See Also:
    
    Collection#inject(Object, Closure)
  - public Iterator iterator()
    
    An identity function for iterators, supporting 'duck-typing' when trying to get an iterator for each object within a collection, some of which may already be iterators.
    
    Returns:
    
    itself
    
    Since:
    
    1.5.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 determining 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
    
    See Also:
    
    GroovyCollections#max(java.util.Collection)
  - 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
    
    See Also:
    
    Collection#max(groovy.lang.Closure)
  - 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:
    
    Collection#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
    
    See Also:
    
    Collection#min(groovy.lang.Closure)
  - 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
    
    See Also:
    
    Collection#min(java.util.Comparator)
  - 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.
    
    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.
    
    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.
    
    Parameters:
    
    comparator - a Comparator used for comparing items
    
    Returns:
    
    the sorted items as an Iterator
    
    Since:
    
    1.5.5
  - 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 of the items
    
    Since:
    
    1.5.5
  - public Object sum(Closure closure)
    
    Sums the result of apply 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 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 of 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 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 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 List toList()
    
    Convert an iterator to a List. The iterator will become exhausted of elements after making this conversion.
    
    Returns:
    
    a List
    
    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 unique()
    
    Returns an iterator equivalent to this iterator all duplicated items removed by using the default 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:
    
    the modified Iterator
    
    Since:
    
    1.5.5
  - public Iterator unique(Closure closure)
    
    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:
    
    closure - 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.
    
    Parameters:
    
    comparator - a Comparator
    
    Returns:
    
    the modified Iterator
    
    Since:
    
    1.5.5

Interface Iterator

Methods Summary

Methods Detail

public boolean any(Closure closure)

public boolean asBoolean()

public Map collectEntries()

public Map collectEntries(Closure transform)

public Map collectEntries(Map collector)

public Map collectEntries(Map collector, Closure transform)

public List collectMany(Closure projection)

public Number count(Closure closure)

public Number count(Object value)

public Map countBy(Closure closure)

public Iterator drop(int num)

public Iterator dropWhile(Closure condition)

public Iterator eachWithIndex(Closure closure)

public boolean every(Closure closure)

public Object getAt(int idx)

public Object inject(Object initialValue, Closure closure)

public Iterator iterator()

public String join(String separator)

public Object max()

public Object max(Closure closure)

public Object max(Comparator comparator)

public Object min()

public Object min(Closure closure)

public Object min(Comparator comparator)

public Iterator reverse()

public int size()

public Iterator sort()

public Iterator sort(Closure closure)

public Iterator sort(Comparator comparator)

public Object sum()

public Object sum(Closure closure)

public Object sum(Object initialValue)

public Object sum(Object initialValue, Closure closure)

public Iterator take(int num)

public Iterator takeWhile(Closure condition)

public List toList()

public Set toSet()

public Iterator unique()

public Iterator unique(Closure closure)

public Iterator unique(Comparator comparator)