Class CollatingIterator<E>
java.lang.Object
org.apache.commons.collections4.iterators.CollatingIterator<E>
- All Implemented Interfaces:
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
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Comparator
<? super E> TheComparator
used to evaluate order.The list ofIterator
s to evaluate.private int
Index of theiterator
from whom the last returned value was obtained.Next
objects peeked from each iterator.private BitSet
Whether or not eachvalues
element has been set. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a newCollatingIterator
.CollatingIterator
(Comparator<? super E> comp) Constructs a newCollatingIterator
that will used the specified comparator for ordering.CollatingIterator
(Comparator<? super E> comp, int initIterCapacity) Constructs a newCollatingIterator
that will used the specified comparator for ordering and have the specified initial capacity.CollatingIterator
(Comparator<? super E> comp, Collection<Iterator<? extends E>> iterators) Constructs a newCollatingIterator
that will use the specified comparator to provide ordered iteration over the collection of iterators.CollatingIterator
(Comparator<? super E> comp, Iterator<? extends E>[] iterators) Constructs a newCollatingIterator
that will use the specified comparator to provide ordered iteration over the array of iterators.CollatingIterator
(Comparator<? super E> comp, Iterator<? extends E> a, Iterator<? extends E> b) Constructs a newCollatingIterator
that will use the specified comparator to provide ordered iteration over the two given iterators. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addIterator
(Iterator<? extends E> iterator) Adds the givenIterator
to the iterators being collated.private boolean
anyHasNext
(List<Iterator<? extends E>> iters) Returnstrue
iff anyIterator
in the given list has a next value.private boolean
anyValueSet
(BitSet set) Returnstrue
iff any bit in the given set istrue
.private void
ThrowsIllegalStateException
if iteration has started viastart()
.private void
clear
(int i) Comparator
<? super E> Gets theComparator
by which collatation occurs.int
Returns the index of the iterator that returned the last element.Gets the list of Iterators (unmodifiable).boolean
hasNext()
Returnstrue
if any child iterator has remaining elements.private int
least()
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
(Comparator<? super E> comp) Sets theComparator
by which collation occurs.void
setIterator
(int index, 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 Details
-
comparator
TheComparator
used to evaluate order. -
iterators
The list ofIterator
s to evaluate. -
values
Next
objects peeked from each iterator. -
valueSet
Whether or not eachvalues
element has been set. -
lastReturned
private int lastReturnedIndex of theiterator
from whom the last returned value was obtained.
-
-
Constructor Details
-
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
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
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(Comparator<? super E> comp, Iterator<? extends E> a, 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:
NullPointerException
- if either iterator is null
-
CollatingIterator
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:
NullPointerException
- if iterators array is or contains null
-
CollatingIterator
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:
NullPointerException
- if the iterators collection is or contains nullClassCastException
- if the iterators collection contains an element that's not anIterator
-
-
Method Details
-
addIterator
Adds the givenIterator
to the iterators being collated.- Parameters:
iterator
- the iterator to add to the collation, must not be null- Throws:
IllegalStateException
- if iteration has startedNullPointerException
- if the iterator is null
-
setIterator
Sets the iterator at the given index.- Parameters:
index
- index of the Iterator to replaceiterator
- Iterator to place at the given index- Throws:
IndexOutOfBoundsException
- if index < 0 or index > size()IllegalStateException
- if iteration has startedNullPointerException
- if the iterator is null
-
getIterators
Gets the list of Iterators (unmodifiable).- Returns:
- the unmodifiable list of iterators added
-
getComparator
Gets theComparator
by which collatation occurs.- Returns:
- the
Comparator
-
setComparator
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:
IllegalStateException
- if iteration has started
-
hasNext
public boolean hasNext()Returnstrue
if any child iterator has remaining elements. -
next
Returns the next ordered element from a child iterator.- Specified by:
next
in interfaceIterator<E>
- 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 interfaceIterator<E>
- Throws:
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:
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
ThrowsIllegalStateException
if iteration has started viastart()
.- Throws:
IllegalStateException
- if iteration started
-
least
private int least()- Throws:
NullPointerException
- if no comparator is set
-
anyValueSet
Returnstrue
iff any bit in the given set istrue
. -
anyHasNext
Returnstrue
iff anyIterator
in the given list has a next value.
-