CollatingIterator

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

All Implemented Interfaces:

java.util.Iterator
```
public class CollatingIterator
extends java.lang.Object
implements java.util.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) $

Field Summary

Fields
Modifier and Type	Field and Description
`private java.util.Comparator`	`comparator` The `Comparator` used to evaluate order.
`private java.util.ArrayList`	`iterators` The list of `Iterator`s to evaluate.
`private int`	`lastReturned` Index of the `iterator` from whom the last returned value was obtained.
`private java.util.ArrayList`	`values` `Next` objects peeked from each iterator.
`private java.util.BitSet`	`valueSet` Whether or not each `values` element has been set.

Constructor Summary

Constructors
Constructor and Description
`CollatingIterator()` Constructs a new `CollatingIterator`.
`CollatingIterator(java.util.Comparator comp)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering.
`CollatingIterator(java.util.Comparator comp, java.util.Collection iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the collection of iterators.
`CollatingIterator(java.util.Comparator comp, int initIterCapacity)` Constructs a new `CollatingIterator` that will used the specified comparator for ordering and have the specified initial capacity.
`CollatingIterator(java.util.Comparator comp, java.util.Iterator[] iterators)` Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the array of iterators.
`CollatingIterator(java.util.Comparator comp, java.util.Iterator a, java.util.Iterator 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(java.util.Iterator iterator)` Adds the given `Iterator` to the iterators being collated.
`private boolean`	`anyHasNext(java.util.ArrayList iters)` Returns `true` iff any `Iterator` in the given list has a next value.
`private boolean`	`anyValueSet(java.util.BitSet set)` Returns `true` iff any bit in the given set is `true`.
`private void`	`checkNotStarted()` Throws `IllegalStateException` if iteration has started via `start()`.
`private void`	`clear(int i)` Clears the `values` and `valueSet` attributes at position i.
`java.util.Comparator`	`getComparator()` Gets the `Comparator` by which collatation occurs.
`java.util.List`	`getIterators()` Gets the list of Iterators (unmodifiable).
`boolean`	`hasNext()` Returns `true` if any child iterator has remaining elements.
`private int`	`least()` Returns the index of the least element in `values`, `setting` any uninitialized values.
`java.lang.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.
`private boolean`	`set(int i)` Sets the `values` and `valueSet` attributes at position i to the next value of the `iterator` at position i, or clear them if the i^th iterator has no next value.
`void`	`setComparator(java.util.Comparator comp)` Sets the `Comparator` by which collation occurs.
`void`	`setIterator(int index, java.util.Iterator iterator)` Sets the iterator at the given index.
`private void`	`start()` Initializes the collating state if it hasn't been already.

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

- Field Detail
  - comparator
```
private java.util.Comparator comparator
```
    The Comparator used to evaluate order.
  - iterators
```
private java.util.ArrayList iterators
```
    The list of Iterators to evaluate.
  - values
```
private java.util.ArrayList values
```
    Next objects peeked from each iterator.
  - valueSet
```
private java.util.BitSet valueSet
```
    Whether or not each values element has been set.
  - lastReturned
```
private int lastReturned
```
    Index of the iterator from whom the last returned value was obtained.
- 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(java.util.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(java.util.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(java.util.Comparator comp,
                         java.util.Iterator a,
                         java.util.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:
    
    java.lang.NullPointerException - if either iterator is null
  - CollatingIterator
```
public CollatingIterator(java.util.Comparator comp,
                         java.util.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:
    
    java.lang.NullPointerException - if iterators array is or contains null
  - CollatingIterator
```
public CollatingIterator(java.util.Comparator comp,
                         java.util.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:
    
    java.lang.NullPointerException - if the iterators collection is or contains null
    
    java.lang.ClassCastException - if the iterators collection contains an element that's not an Iterator
- Method Detail
  - addIterator
```
public void addIterator(java.util.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:
    
    java.lang.IllegalStateException - if iteration has started
    
    java.lang.NullPointerException - if the iterator is null
  - setIterator
```
public void setIterator(int index,
                        java.util.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:
    
    java.lang.IndexOutOfBoundsException - if index < 0 or index > size()
    
    java.lang.IllegalStateException - if iteration has started
    
    java.lang.NullPointerException - if the iterator is null
  - getIterators
```
public java.util.List getIterators()
```
    Gets the list of Iterators (unmodifiable).
    
    Returns:
    
    the unmodifiable list of iterators added
  - getComparator
```
public java.util.Comparator getComparator()
```
    Gets the Comparator by which collatation occurs.
  - setComparator
```
public void setComparator(java.util.Comparator comp)
```
    Sets the Comparator by which collation occurs.
    
    Throws:
    
    java.lang.IllegalStateException - if iteration has started
  - hasNext
```
public boolean hasNext()
```
    Returns true if any child iterator has remaining elements.
    
    Specified by:
    
    hasNext in interface java.util.Iterator
    
    Returns:
    
    true if this iterator has remaining elements
  - next
```
public java.lang.Object next()
                      throws java.util.NoSuchElementException
```
    Returns the next ordered element from a child iterator.
    
    Specified by:
    
    next in interface java.util.Iterator
    
    Returns:
    
    the next ordered element
    
    Throws:
    
    java.util.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 java.util.Iterator
    
    Throws:
    
    java.lang.IllegalStateException - if there is no last returned element, or if the last returned element has already been removed
  - start
```
private void start()
```
    Initializes the collating state if it hasn't been already.
  - set
```
private boolean set(int i)
```
    Sets the values and valueSet attributes at position i to the next value of the iterator at position i, or clear them if the i^th iterator has no next value.
    
    Returns:
    
    false iff there was no value to set
  - clear
```
private void clear(int i)
```
    Clears the values and valueSet attributes at position i.
  - checkNotStarted
```
private void checkNotStarted()
                      throws java.lang.IllegalStateException
```
    Throws IllegalStateException if iteration has started via start().
    
    Throws:
    
    java.lang.IllegalStateException - if iteration started
  - least
```
private int least()
```
    Returns the index of the least element in values, setting any uninitialized values.
    
    Throws:
    
    java.lang.IllegalStateException
  - anyValueSet
```
private boolean anyValueSet(java.util.BitSet set)
```
    Returns true iff any bit in the given set is true.
  - anyHasNext
```
private boolean anyHasNext(java.util.ArrayList iters)
```
    Returns true iff any Iterator in the given list has a next value.

Class CollatingIterator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Field Detail

comparator

iterators

values

valueSet

lastReturned

Constructor Detail

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

CollatingIterator

Method Detail

addIterator

setIterator

getIterators

getComparator

setComparator

hasNext

next

remove

start

set

clear

checkNotStarted

least

anyValueSet

anyHasNext