Apache Commons Collections 4.4 · org.apache.commons.collections4.iterators.CollatingIterator

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

Constructor Summary

Access	Constructor and Description
public	CollatingIterator() Constructs a new `CollatingIterator`.
public	CollatingIterator(final Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. comp) Constructs a new `CollatingIterator` that will used the specified comparator for ordering.
public	CollatingIterator(final Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. comp, final int the initial capacity for the internal list of child iterators initIterCapacity) Constructs a new `CollatingIterator` that will used the specified comparator for ordering and have the specified initial capacity.
public	CollatingIterator(final Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. comp, final Iterator<? extends E> the first child ordered iterator a, final Iterator<? extends E> the second child ordered iterator b) Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the two given iterators.
public	CollatingIterator(final Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. comp, final Iterator<? extends E>[] the array of iterators iterators) Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the array of iterators.
public	CollatingIterator(final Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. comp, final Collection<Iterator<? extends E>> the collection of iterators iterators) Constructs a new `CollatingIterator` that will use the specified comparator to provide ordered iteration over the collection of iterators.

Method Summary

Modifier and Type	Method and Description
public void	addIterator(final Iterator<? extends E> the iterator to add to the collation, must not be null iterator) Adds the given `Iterator` to the iterators being collated.
private boolean	anyHasNext(final List<Iterator<? extends E>> iters) Returns `true` iff any `Iterator` in the given list has a next value.
private boolean	anyValueSet(final 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(final int i) Clears the `values` and `valueSet` attributes at position i.
public Comparator<? super E>	Returns: the `Comparator` getComparator() Gets the `Comparator` by which collatation occurs.
public int	Returns: the index of the iterator that returned the last element getIteratorIndex() Returns the index of the iterator that returned the last element.
public List<Iterator<? extends E>>	Returns: the unmodifiable list of iterators added getIterators() Gets the list of Iterators (unmodifiable).
public boolean	Returns: true if this iterator has remaining elements hasNext() Implements java.util.Iterator.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.
public E	Returns: the next ordered element next() Implements java.util.Iterator.next. Returns the next ordered element from a child iterator.
public void	remove() Overrides default java.util.Iterator.remove. Removes the last returned element from the child iterator that produced it.
private boolean	Returns: `false` iff there was no value to set set(final 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.
public void	setComparator(final Comparator<? super E> the `Comparator` to set comp) Sets the `Comparator` by which collation occurs.
public void	setIterator(final int index of the Iterator to replace index, final Iterator<? extends E> Iterator to place at the given index iterator) Sets the iterator at the given index.
private void	start() Initializes the collating state if it hasn't been already.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

comparator	back to summary
private Comparator<? super E> comparator The `Comparator` used to evaluate order.

iterators	back to summary
private List<Iterator<? extends E>> iterators The list of `Iterator`s to evaluate.

lastReturned	back to summary
private int lastReturned Index of the `iterator` from whom the last returned value was obtained.

values	back to summary
private List<E> values `Next` objects peeked from each iterator.

valueSet	back to summary
private BitSet valueSet Whether or not each `values` element has been set.

Constructor Detail

CollatingIterator	back to summary
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 back to summary

CollatingIterator	back to summary
public CollatingIterator(final 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:Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on.

public CollatingIterator(final 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:Comparator<? super E>: the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.

CollatingIterator back to summary

CollatingIterator	back to summary
public CollatingIterator(final Comparator<? super E> comp, final 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:Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. initIterCapacity:int the initial capacity for the internal list of child iterators

public CollatingIterator(final Comparator<? super E> comp, final 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:Comparator<? super E>: the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
initIterCapacity:int: the initial capacity for the internal list of child iterators

CollatingIterator back to summary

CollatingIterator	back to summary
public CollatingIterator(final Comparator<? super E> comp, final Iterator<? extends E> a, final 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:Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. a:Iterator<? extends E> the first child ordered iterator b:Iterator<? extends E> the second child ordered iterator Exceptions NullPointerException: if either iterator is null

public CollatingIterator(final Comparator<? super E> comp, final Iterator<? extends E> a, final 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:Comparator<? super E>: the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
a:Iterator<? extends E>: the first child ordered iterator
b:Iterator<? extends E>: the second child ordered iterator

Exceptions

NullPointerException:: if either iterator is null

CollatingIterator back to summary

CollatingIterator	back to summary
public CollatingIterator(final Comparator<? super E> comp, final 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:Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. iterators:Iterator<? extends E>[] the array of iterators Exceptions NullPointerException: if iterators array is or contains null

public CollatingIterator(final Comparator<? super E> comp, final 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:Comparator<? super E>: the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
iterators:Iterator<? extends E>[]: the array of iterators

Exceptions

NullPointerException:: if iterators array is or contains null

CollatingIterator back to summary

CollatingIterator	back to summary
public CollatingIterator(final Comparator<? super E> comp, final Collection<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:Comparator<? super E> the comparator to use to sort; must not be null, unless you'll be invoking `setComparator(Comparator)` later on. iterators:Collection<Iterator<? extends E>> the collection of iterators Exceptions NullPointerException: if the iterators collection is or contains null ClassCastException: if the iterators collection contains an element that's not an `Iterator`

public CollatingIterator(final Comparator<? super E> comp, final Collection<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:Comparator<? super E>: the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
iterators:Collection<Iterator<? extends E>>: the collection of iterators

Exceptions

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 back to summary

addIterator	back to summary
public void addIterator(final Iterator<? extends E> iterator) Adds the given `Iterator` to the iterators being collated. Parameters iterator:Iterator<? extends E> the iterator to add to the collation, must not be null Exceptions IllegalStateException: if iteration has started NullPointerException: if the iterator is null

public void addIterator(final Iterator<? extends E> iterator)

Adds the given Iterator to the iterators being collated.

Parameters

iterator:Iterator<? extends E>: the iterator to add to the collation, must not be null

Exceptions

IllegalStateException:: if iteration has started
NullPointerException:: if the iterator is null

anyHasNext	back to summary
private boolean anyHasNext(final List<Iterator<? extends E>> iters) Returns `true` iff any `Iterator` in the given list has a next value.

anyValueSet	back to summary
private boolean anyValueSet(final BitSet set) Returns `true` iff any bit in the given set is `true`.

checkNotStarted back to summary

checkNotStarted	back to summary
private void checkNotStarted() throws IllegalStateException Throws `IllegalStateException` if iteration has started via `start`. Exceptions IllegalStateException: if iteration started

private void checkNotStarted() throws IllegalStateException

Throws IllegalStateException if iteration has started via start.

Exceptions

IllegalStateException:: if iteration started

clear	back to summary
private void clear(final int i) Clears the `values` and `valueSet` attributes at position i.

getComparator back to summary

getComparator	back to summary
public Comparator<? super E> getComparator() Gets the `Comparator` by which collatation occurs. Returns:Comparator<? super E> the `Comparator`

public Comparator<? super E> getComparator()

Gets the Comparator by which collatation occurs.

Returns:Comparator<? super E>: the Comparator

getIteratorIndex	back to summary
public int getIteratorIndex() Returns the index of the iterator that returned the last element. Returns:int the index of the iterator that returned the last element Exceptions IllegalStateException: if there is no last returned element

getIteratorIndex

back to summary

public int getIteratorIndex()

Returns the index of the iterator that returned the last element.

Returns:int

the index of the iterator that returned the last element

Exceptions

IllegalStateException:: if there is no last returned element

getIterators	back to summary
public List<Iterator<? extends E>> getIterators() Gets the list of Iterators (unmodifiable). Returns:List<Iterator<? extends E>> the unmodifiable list of iterators added

getIterators

back to summary

public List<Iterator<? extends E>> getIterators()

Gets the list of Iterators (unmodifiable).

Returns:List<Iterator<? extends E>>: the unmodifiable list of iterators added

hasNext back to summary

hasNext	back to summary
public boolean hasNext() Implements java.util.Iterator.hasNext. Returns `true` if any child iterator has remaining elements. Returns:boolean true if this iterator has remaining elements Annotations @Override

public boolean hasNext()

Implements java.util.Iterator.hasNext.

Returns true if any child iterator has remaining elements.

Returns:boolean

true if this iterator has remaining elements

Annotations

@Override

least back to summary

least	back to summary
private int least() Returns the index of the least element in `values`, `setting` any uninitialized values. Exceptions NullPointerException: if no comparator is set

private int least()

Returns the index of the least element in values, setting any uninitialized values.

Exceptions

NullPointerException:: if no comparator is set

next	back to summary
public E next() throws NoSuchElementException Implements java.util.Iterator.next. Returns the next ordered element from a child iterator. Returns:E the next ordered element Annotations @Override Exceptions NoSuchElementException: if no child iterator has any more elements

back to summary

public E next() throws NoSuchElementException

Implements java.util.Iterator.next.

Returns the next ordered element from a child iterator.

Returns:E

the next ordered element

Annotations

@Override

Exceptions

NoSuchElementException:: if no child iterator has any more elements

remove	back to summary
public void remove() Overrides default java.util.Iterator.remove. Removes the last returned element from the child iterator that produced it. Annotations @Override Exceptions IllegalStateException: if there is no last returned element, or if the last returned element has already been removed

remove

back to summary

public void remove()

Overrides default java.util.Iterator.remove.

Removes the last returned element from the child iterator that produced it.

Annotations

@Override

Exceptions

IllegalStateException:: if there is no last returned element, or if the last returned element has already been removed

set back to summary

set	back to summary
private boolean set(final 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:boolean `false` iff there was no value to set

private boolean set(final 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:boolean: false iff there was no value to set

setComparator back to summary

setComparator	back to summary
public void setComparator(final 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 `java.lang.Comparable` interface), then use the `org.apache.commons.collections4.comparators.ComparableComparator`. Parameters comp:Comparator<? super E> the `Comparator` to set Exceptions IllegalStateException: if iteration has started

public void setComparator(final 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 java.lang.Comparable interface), then use the org.apache.commons.collections4.comparators.ComparableComparator.

Parameters

comp:Comparator<? super E>: the Comparator to set

Exceptions

IllegalStateException:: if iteration has started

setIterator	back to summary
public void setIterator(final int index, final Iterator<? extends E> iterator) Sets the iterator at the given index. Parameters index:int index of the Iterator to replace iterator:Iterator<? extends E> Iterator to place at the given index Exceptions IndexOutOfBoundsException: if index < 0 or index > size() IllegalStateException: if iteration has started NullPointerException: if the iterator is null

setIterator

back to summary

public void setIterator(final int index, final Iterator<? extends E> iterator)

Sets the iterator at the given index.

Parameters

index:int: index of the Iterator to replace
iterator:Iterator<? extends E>: Iterator to place at the given index

Exceptions

IndexOutOfBoundsException:: if index < 0 or index > size()
IllegalStateException:: if iteration has started
NullPointerException:: if the iterator is null

start	back to summary
private void start() Initializes the collating state if it hasn't been already.

public Class CollatingIterator<E>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail