org.apache.commons.collections4.iterators

Class CollatingIterator<E>

java.lang.Object

org.apache.commons.collections4.iterators.CollatingIterator<E>

All Implemented Interfaces:

java.util.Iterator<E>

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

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Comparator<? super E>	comparator The Comparator used to evaluate order.
private java.util.ArrayList<java.util.Iterator<? extends E>>	iterators The list of Iterators to evaluate.
private int	lastReturned Index of the iterator from whom the last returned value was obtained.
private java.util.ArrayList<E>	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<? super E> comp) Constructs a new CollatingIterator that will used the specified comparator for ordering.
CollatingIterator(java.util.Comparator<? super E> comp, java.util.Collection<java.util.Iterator<? extends E>> iterators) Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
CollatingIterator(java.util.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(java.util.Comparator<? super E> comp, java.util.Iterator<? extends E>[] iterators) Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
CollatingIterator(java.util.Comparator<? super E> comp, java.util.Iterator<? extends E> a, java.util.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 and Description
void	addIterator(java.util.Iterator<? extends E> iterator) Adds the given Iterator to the iterators being collated.
private boolean	anyHasNext(java.util.ArrayList<java.util.Iterator<? extends E>> 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<? super E>	getComparator() Gets the Comparator by which collatation occurs.
int	getIteratorIndex() Returns the index of the iterator that returned the last element.
java.util.List<java.util.Iterator<? extends E>>	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.
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.
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 ith iterator has no next value.
void	setComparator(java.util.Comparator<? super E> comp) Sets the Comparator by which collation occurs.
void	setIterator(int index, java.util.Iterator<? extends E> 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<? super E> comparator

The Comparator used to evaluate order.

iterators

private java.util.ArrayList<java.util.Iterator<? extends E>> iterators

The list of Iterators to evaluate.

values

private java.util.ArrayList<E> 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. 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(java.util.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(java.util.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(java.util.Comparator<? super E> comp,
                         java.util.Iterator<? extends E> a,
                         java.util.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:

java.lang.NullPointerException - if either iterator is null

CollatingIterator

public CollatingIterator(java.util.Comparator<? super E> comp,
                         java.util.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:

java.lang.NullPointerException - if iterators array is or contains null

CollatingIterator

public CollatingIterator(java.util.Comparator<? super E> comp,
                         java.util.Collection<java.util.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:

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<? 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:

java.lang.IllegalStateException - if iteration has started

java.lang.NullPointerException - if the iterator is null

setIterator

public void setIterator(int index,
                        java.util.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:

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<java.util.Iterator<? extends E>> getIterators()

Gets the list of Iterators (unmodifiable).

Returns:

the unmodifiable list of iterators added

getComparator

public java.util.Comparator<? super E> getComparator()

Gets the Comparator by which collatation occurs.

Returns:

the Comparator

setComparator

public void setComparator(java.util.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:

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

Returns:

true if this iterator has remaining elements

next

public E next()
       throws java.util.NoSuchElementException

Returns the next ordered element from a child iterator.

Specified by:

next in interface java.util.Iterator<E>

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

Throws:

java.lang.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:

java.lang.IllegalStateException - if there is no last returned element

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.NullPointerException - if no comparator is set

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<java.util.Iterator<? extends E>> iters)

Returns true iff any Iterator in the given list has a next value.