Package org.revapi

Class CoIterator<E>

java.lang.Object

org.revapi.CoIterator<E>

public final class CoIterator<E>
extends Object

Heavily inspired by the equivalently named class in Clirr 0.6.

This is an iterator that walks a pair of collections, returning matching pairs from the set.

When an element is present in the left set but there is no equal object in the right set, the pair (leftobj, null) is returned.

When an element is present in the right set but there is no equal object in the left set, the pair (null, rightobj) is returned.

When an element in one set has an equal element in the other set, the pair (leftobj, rightobj) is returned.

Note that the phrase "pair is returned" above actually means that the getLeft and getRight methods on the iterator return those objects; the pair is "conceptual" rather than a physical Pair instance. This avoids instantiating an object to represent the pair for each step of the iterator which would not be efficient.

Note also that elements from the sets are always returned in the iteration order.

Since:

0.1

Author:

Simon Kitching, Lukas Krejci

Constructor Summary

Constructors

Constructor	Description
CoIterator(Iterator<? extends E> left, Iterator<? extends E> right)	Assumes the iterators iterate over comparable elements and uses their natural ordering instead of an explicit comparator.
CoIterator(Iterator<? extends E> left, Iterator<? extends E> right, Comparator<? super E> comparator)	The iterators must iterate over sorted collections otherwise this instance might not produce the intended results.

Method Summary

Modifier and Type	Method	Description
E	getLeft()	After calling next(), this will contain the next element from the "left" collection.
E	getRight()	After calling next(), this will contain the next element from the "right" collection.
boolean	hasNext()
void	next()	Use getLeft() and getRight() to get the next elements from the two iterated collections.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CoIterator

public CoIterator(Iterator<? extends E> left,
                  Iterator<? extends E> right,
                  Comparator<? super E> comparator)

The iterators must iterate over sorted collections otherwise this instance might not produce the intended results.

Also, the iterators must not ever return null - i.e. the collections must not contain null values otherwise the behavior of the iteration is undefined.

Parameters:

left - the iterator over "left" collection

right - the iterator over "right" collection

comparator - the comparator used to sort the collections (this must have been done prior to calling this constructor)

CoIterator

public CoIterator(Iterator<? extends E> left,
                  Iterator<? extends E> right)

Assumes the iterators iterate over comparable elements and uses their natural ordering instead of an explicit comparator.

If E is not at the same time comparable, calling next() will fail with a class cast exception at the first mutual comparison of elements from the two collections.

Parameters:

left - the iterator over the "left" collection

right - the iterator over the "right" collection

See Also:

CoIterator(java.util.Iterator, java.util.Iterator, java.util.Comparator)

Method Detail

hasNext

public boolean hasNext()

next

public void next()

Use getLeft() and getRight() to get the next elements from the two iterated collections.

getLeft

public E getLeft()

After calling next(), this will contain the next element from the "left" collection.

Returns:

the next element from the left collection

getRight

public E getRight()

After calling next(), this will contain the next element from the "right" collection.

Returns:

the next element from the right collection