# Class CollatingIterator<E>

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

Type Parameters:
  `E` - the type of elements returned by this iterator.

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
  Description
  `CollatingIterator()`
  Constructs a new `CollatingIterator`.
  `CollatingIterator(Comparator<? super E> comp)`
  Constructs a new `CollatingIterator` that will use the specified comparator for ordering.
  `CollatingIterator(Comparator<? super E> comp, int initIterCapacity)`
  Constructs a new `CollatingIterator` that will use the specified comparator for ordering and have the specified initial capacity.
  `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, 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

  Modifier and Type
  Method
  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 collation occurs.
  `int`
  `getIteratorIndex()`
  Gets 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 Details

  - ### 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 use 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, 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`

  - ### CollatingIterator

    public CollatingIterator(Comparator<? super E> comp, int initIterCapacity)
    Constructs a new `CollatingIterator` that will use 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

- ## Method Details

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

  - ### getComparator

    public Comparator<? super E> getComparator()
    Gets the `Comparator` by which collation occurs.
    Returns:
      the `Comparator`

  - ### getIteratorIndex

    public int getIteratorIndex()
    Gets 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

  - ### getIterators

    public List<Iterator<? extends E>> getIterators()
    Gets the list of Iterators (unmodifiable).
    Returns:
      the unmodifiable list of iterators added

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

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

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