org.apache.commons.collections4.iterators

## Class CollatingIterator<E>

- 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
  Version:
    $Id: CollatingIterator.java 1477802 2013-04-30 20:01:28Z tn $

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

    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`

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

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.