org.apache.commons.collections.iterators

## Class CollatingIterator

- java.lang.Object
- - org.apache.commons.collections.iterators.CollatingIterator

- All Implemented Interfaces:
    Iterator

      public class CollatingIterator
      extends Object
      implements Iterator

  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:
    Commons Collections 2.1
  Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Rodney Waldhoff, Stephen Colebourne

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CollatingIterator()` Constructs a new `CollatingIterator`.
    `CollatingIterator(Comparator comp)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering.
    `CollatingIterator(Comparator comp, Collection iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the collection of iterators.
    `CollatingIterator(Comparator comp, int initIterCapacity)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering and have the specified initial capacity.
    `CollatingIterator(Comparator comp, Iterator[] iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the array of iterators.
    `CollatingIterator(Comparator comp, Iterator a, Iterator 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 iterator)` Adds the given `Iterator` to the iterators being collated.
    `Comparator` | `getComparator()` Gets the `Comparator` by which collatation occurs.
    `List` | `getIterators()` Gets the list of Iterators (unmodifiable).
    `boolean` | `hasNext()` Returns `true` if any child iterator has remaining elements.
    `Object` | `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 comp)` Sets the `Comparator` by which collation occurs.
    `void` | `setIterator(int index, Iterator 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`. Natural sort order will be used, and child iterators will have to be manually added using the `addIterator(Iterator)` method.

    - #### CollatingIterator

          public CollatingIterator(Comparator 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, or null to use natural sort order

    - #### CollatingIterator

          public CollatingIterator(Comparator 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, or null to use natural sort order
        `initIterCapacity` - the initial capacity for the internal list of child iterators

    - #### CollatingIterator

          public CollatingIterator(Comparator comp,
                           Iterator a,
                           Iterator 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, or null to use natural sort order
        `a` - the first child ordered iterator
        `b` - the second child ordered iterator
      Throws:
        `NullPointerException` - if either iterator is null

    - #### CollatingIterator

          public CollatingIterator(Comparator comp,
                           Iterator[] 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, or null to use natural sort order
        `iterators` - the array of iterators
      Throws:
        `NullPointerException` - if iterators array is or contains null

    - #### CollatingIterator

          public CollatingIterator(Comparator comp,
                           Collection 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, or null to use natural sort order
        `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 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 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 getIterators()

      Gets the list of Iterators (unmodifiable).
      Returns:
        the unmodifiable list of iterators added

    - #### getComparator

          public Comparator getComparator()

      Gets the `Comparator` by which collatation occurs.

    - #### setComparator

          public void setComparator(Comparator comp)

      Sets the `Comparator` by which collation occurs.
      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`
      Returns:
        true if this iterator has remaining elements

    - #### next

          public Object next()
                      throws NoSuchElementException

      Returns the next ordered element from a child iterator.
      Specified by:
        `next` in interface `Iterator`
      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`
      Throws:
        `IllegalStateException` - if there is no last returned element, or if the last returned element has already been removed

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