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
instancesA
andB
, thenext()
method on this iterator will return the lesser ofA.next()
andB.next()
.- Since:
- 2.1
-
-
Field Summary
Fields Modifier and Type Field Description private java.util.Comparator<? super E>
comparator
TheComparator
used to evaluate order.private java.util.List<java.util.Iterator<? extends E>>
iterators
The list ofIterator
s to evaluate.private int
lastReturned
Index of theiterator
from whom the last returned value was obtained.private java.util.List<E>
values
Next
objects peeked from each iterator.private java.util.BitSet
valueSet
Whether or not eachvalues
element has been set.
-
Constructor Summary
Constructors Constructor Description CollatingIterator()
Constructs a newCollatingIterator
.CollatingIterator(java.util.Comparator<? super E> comp)
Constructs a newCollatingIterator
that will used the specified comparator for ordering.CollatingIterator(java.util.Comparator<? super E> comp, int initIterCapacity)
Constructs a newCollatingIterator
that will used the specified comparator for ordering and have the specified initial capacity.CollatingIterator(java.util.Comparator<? super E> comp, java.util.Collection<java.util.Iterator<? extends E>> iterators)
Constructs a newCollatingIterator
that will use the specified comparator to provide ordered iteration over the collection of iterators.CollatingIterator(java.util.Comparator<? super E> comp, java.util.Iterator<? extends E>[] iterators)
Constructs a newCollatingIterator
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 newCollatingIterator
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 Description void
addIterator(java.util.Iterator<? extends E> iterator)
Adds the givenIterator
to the iterators being collated.private boolean
anyHasNext(java.util.List<java.util.Iterator<? extends E>> iters)
Returnstrue
iff anyIterator
in the given list has a next value.private boolean
anyValueSet(java.util.BitSet set)
Returnstrue
iff any bit in the given set istrue
.private void
checkNotStarted()
ThrowsIllegalStateException
if iteration has started viastart()
.private void
clear(int i)
java.util.Comparator<? super E>
getComparator()
Gets theComparator
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()
Returnstrue
if any child iterator has remaining elements.private int
least()
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)
void
setComparator(java.util.Comparator<? super E> comp)
Sets theComparator
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.
-
-
-
Field Detail
-
comparator
private java.util.Comparator<? super E> comparator
TheComparator
used to evaluate order.
-
iterators
private java.util.List<java.util.Iterator<? extends E>> iterators
The list ofIterator
s to evaluate.
-
values
private java.util.List<E> values
Next
objects peeked from each iterator.
-
valueSet
private java.util.BitSet valueSet
Whether or not eachvalues
element has been set.
-
lastReturned
private int lastReturned
Index of theiterator
from whom the last returned value was obtained.
-
-
Constructor Detail
-
CollatingIterator
public CollatingIterator()
Constructs a newCollatingIterator
. A comparator must be set by callingsetComparator(Comparator)
before invokinghasNext()
, ornext()
for the first time. Child iterators will have to be manually added using theaddIterator(Iterator)
method.
-
CollatingIterator
public CollatingIterator(java.util.Comparator<? super E> comp)
Constructs a newCollatingIterator
that will used the specified comparator for ordering. Child iterators will have to be manually added using theaddIterator(Iterator)
method.- Parameters:
comp
- the comparator to use to sort; must not be null, unless you'll be invokingsetComparator(Comparator)
later on.
-
CollatingIterator
public CollatingIterator(java.util.Comparator<? super E> comp, int initIterCapacity)
Constructs a newCollatingIterator
that will used the specified comparator for ordering and have the specified initial capacity. Child iterators will have to be manually added using theaddIterator(Iterator)
method.- Parameters:
comp
- the comparator to use to sort; must not be null, unless you'll be invokingsetComparator(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 newCollatingIterator
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 invokingsetComparator(Comparator)
later on.a
- the first child ordered iteratorb
- 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 newCollatingIterator
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 invokingsetComparator(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 newCollatingIterator
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 invokingsetComparator(Comparator)
later on.iterators
- the collection of iterators- Throws:
java.lang.NullPointerException
- if the iterators collection is or contains nulljava.lang.ClassCastException
- if the iterators collection contains an element that's not anIterator
-
-
Method Detail
-
addIterator
public void addIterator(java.util.Iterator<? extends E> iterator)
Adds the givenIterator
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 startedjava.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 replaceiterator
- Iterator to place at the given index- Throws:
java.lang.IndexOutOfBoundsException
- if index < 0 or index > size()java.lang.IllegalStateException
- if iteration has startedjava.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 theComparator
by which collatation occurs.- Returns:
- the
Comparator
-
setComparator
public void setComparator(java.util.Comparator<? super E> comp)
Sets theComparator
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 theComparable
interface), then use theComparableComparator
.- Parameters:
comp
- theComparator
to set- Throws:
java.lang.IllegalStateException
- if iteration has started
-
hasNext
public boolean hasNext()
Returnstrue
if any child iterator has remaining elements.- Specified by:
hasNext
in interfacejava.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 interfacejava.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 interfacejava.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 thevalues
andvalueSet
attributes at position i to the next value of theiterator
at position i, or clear them if the ith iterator has no next value.- Returns:
false
iff there was no value to set
-
clear
private void clear(int i)
-
checkNotStarted
private void checkNotStarted() throws java.lang.IllegalStateException
ThrowsIllegalStateException
if iteration has started viastart()
.- Throws:
java.lang.IllegalStateException
- if iteration started
-
least
private int least()
- Throws:
java.lang.NullPointerException
- if no comparator is set
-
anyValueSet
private boolean anyValueSet(java.util.BitSet set)
Returnstrue
iff any bit in the given set istrue
.
-
anyHasNext
private boolean anyHasNext(java.util.List<java.util.Iterator<? extends E>> iters)
Returnstrue
iff anyIterator
in the given list has a next value.
-
-