## 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: 1.13 $ $Date: 2004/02/18 00:59:50 $
Author:
  Rodney Waldhoff, Stephen Colebourne

Constructor Summary
`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
`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-2005 Apache Software Foundation. All Rights Reserved.