CollatingIterator

java.lang.Object
- org.apache.commons.collections4.iterators.CollatingIterator<E>

All Implemented Interfaces:

Iterator<E>
```
public class CollatingIterator<E>
extends Object
implements Iterator<E>
```
Provides an ordered iteration over the elements contained in a collection of ordered Iterators.
Given two ordered Iterator instances A and B, the next() method on this iterator will return the lesser of A.next() and B.next().

Since:

2.1

Constructor Summary

Constructors

Constructor and Description
`CollatingIterator()` Constructs a new `CollatingIterator`.
`CollatingIterator(Comparator<? super E> comp)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering.
`CollatingIterator(Comparator<? super E> comp, Collection<Iterator<? extends E>> iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the collection of iterators.
`CollatingIterator(Comparator<? super E> comp, int initIterCapacity)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering and have the specified initial capacity.
`CollatingIterator(Comparator<? super E> comp, Iterator<? extends E>[] iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the array of iterators.
`CollatingIterator(Comparator<? super E> comp, Iterator<? extends E> a, Iterator<? extends E> b)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the two given iterators.

Method Summary

All Methods

Instance Methods

Concrete Methods
Modifier and Type	Method and Description
`void`	`addIterator(Iterator<? extends E> iterator)` Adds the given `Iterator` to the iterators being collated.
`Comparator<? super E>`	`getComparator()` Gets the `Comparator` by which collatation occurs.
`int`	`getIteratorIndex()` Returns the index of the iterator that returned the last element.
`List<Iterator<? extends E>>`	`getIterators()` Gets the list of Iterators (unmodifiable).
`boolean`	`hasNext()` Returns `true` if any child iterator has remaining elements.
`E`	`next()` Returns the next ordered element from a child iterator.
`void`	`remove()` Removes the last returned element from the child iterator that produced it.
`void`	`setComparator(Comparator<? super E> comp)` Sets the `Comparator` by which collation occurs.
`void`	`setIterator(int index, Iterator<? extends E> iterator)` Sets the iterator at the given index.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator
forEachRemaining

- Constructor Detail
  - CollatingIterator
```
public CollatingIterator()
```
    Constructs a new CollatingIterator. A comparator must be set by calling setComparator(Comparator) before invoking hasNext(), or next() for the first time. Child iterators will have to be manually added using the addIterator(Iterator) method.
  - CollatingIterator
```
public CollatingIterator(Comparator<? super E> comp)
```
    Constructs a new CollatingIterator that will used the specified comparator for ordering. Child iterators will have to be manually added using the addIterator(Iterator) method.
    
    Parameters:
    
    comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
  - CollatingIterator
```
public CollatingIterator(Comparator<? super E> comp,
                         int initIterCapacity)
```
    Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity. Child iterators will have to be manually added using the addIterator(Iterator) method.
    
    Parameters:
    
    comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
    
    initIterCapacity - the initial capacity for the internal list of child iterators
  - CollatingIterator
```
public CollatingIterator(Comparator<? super E> comp,
                         Iterator<? extends E> a,
                         Iterator<? extends E> b)
```
    Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.
    
    Parameters:
    
    comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
    
    a - the first child ordered iterator
    
    b - the second child ordered iterator
    
    Throws:
    
    NullPointerException - if either iterator is null
  - CollatingIterator
```
public CollatingIterator(Comparator<? super E> comp,
                         Iterator<? extends E>[] iterators)
```
    Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
    
    Parameters:
    
    comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
    
    iterators - the array of iterators
    
    Throws:
    
    NullPointerException - if iterators array is or contains null
  - CollatingIterator
```
public CollatingIterator(Comparator<? super E> comp,
                         Collection<Iterator<? extends E>> iterators)
```
    Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
    
    Parameters:
    
    comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
    
    iterators - the collection of iterators
    
    Throws:
    
    NullPointerException - if the iterators collection is or contains null
    
    ClassCastException - if the iterators collection contains an element that's not an Iterator
- Method Detail
  - addIterator
```
public void addIterator(Iterator<? extends E> iterator)
```
    Adds the given Iterator to the iterators being collated.
    
    Parameters:
    
    iterator - the iterator to add to the collation, must not be null
    
    Throws:
    
    IllegalStateException - if iteration has started
    
    NullPointerException - if the iterator is null
  - setIterator
```
public void setIterator(int index,
                        Iterator<? extends E> iterator)
```
    Sets the iterator at the given index.
    
    Parameters:
    
    index - index of the Iterator to replace
    
    iterator - Iterator to place at the given index
    
    Throws:
    
    IndexOutOfBoundsException - if index < 0 or index > size()
    
    IllegalStateException - if iteration has started
    
    NullPointerException - if the iterator is null
  - getIterators
```
public List<Iterator<? extends E>> getIterators()
```
    Gets the list of Iterators (unmodifiable).
    
    Returns:
    
    the unmodifiable list of iterators added
  - getComparator
```
public Comparator<? super E> getComparator()
```
    Gets the Comparator by which collatation occurs.
    
    Returns:
    
    the Comparator
  - setComparator
```
public void setComparator(Comparator<? super E> comp)
```
    Sets the Comparator by which collation occurs. If you would like to use the natural sort order (or, in other words, if the elements in the iterators are implementing the Comparable interface), then use the ComparableComparator.
    
    Parameters:
    
    comp - the Comparator to set
    
    Throws:
    
    IllegalStateException - if iteration has started
  - hasNext
```
public boolean hasNext()
```
    Returns true if any child iterator has remaining elements.
    
    Specified by:
    
    hasNext in interface Iterator<E>
    
    Returns:
    
    true if this iterator has remaining elements
  - next
```
public E next()
       throws NoSuchElementException
```
    Returns the next ordered element from a child iterator.
    
    Specified by:
    
    next in interface Iterator<E>
    
    Returns:
    
    the next ordered element
    
    Throws:
    
    NoSuchElementException - if no child iterator has any more elements
  - remove
```
public void remove()
```
    Removes the last returned element from the child iterator that produced it.
    
    Specified by:
    
    remove in interface Iterator<E>
    
    Throws:
    
    IllegalStateException - if there is no last returned element, or if the last returned element has already been removed
  - getIteratorIndex
```
public int getIteratorIndex()
```
    Returns the index of the iterator that returned the last element.
    
    Returns:
    
    the index of the iterator that returned the last element
    
    Throws:
    
    IllegalStateException - if there is no last returned element

Class CollatingIterator<E>

Constructor Summary

Constructors

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Constructor Detail

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

Method Detail

addIterator

setIterator

getIterators

getComparator

setComparator

hasNext

next

remove

getIteratorIndex