net.sf.clirr.core.internal
Class CoIterator

java.lang.Object
  net.sf.clirr.core.internal.CoIterator

public final class CoIterator
extends java.lang.Object

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 order defined by the provided comparator.

Author:

Simon Kitching.

Constructor Summary

CoIterator(java.util.Comparator comparator, java.util.Collection left, java.util.Collection right)
Iterate over the two collections, using the provided comparator.

CoIterator(java.util.Comparator comparator, java.lang.Object[] left, java.lang.Object[] right)
Iterate over the objects in the two arrays, using the provided comparator.

Method Summary

java.lang.Object	getLeft() Return an object from the "left" collection specified to this object's constructor.
java.lang.Object	getRight() See getLeft.
boolean	hasNext() Indicates whether there are any more elements to be returned.
void	next() Moves this iterator object to refer to the next "pair" of objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

CoIterator

public CoIterator(java.util.Comparator comparator,
                  java.util.Collection left,
                  java.util.Collection right)

Iterate over the two collections, using the provided comparator.

The collections are not modified by this iterator.

Parameters:

comparator - is used to compare elements from the two collections. If null, then the objects in the collections are expected to implement the Comparable interface.

CoIterator

public CoIterator(java.util.Comparator comparator,
                  java.lang.Object[] left,
                  java.lang.Object[] right)

Iterate over the objects in the two arrays, using the provided comparator.

The arrays are not modified by this iterator. In particular, the iterator returns the elements in ascending order, but the actual arrays passed in here are cloned so that they are not modified.

Parameters:

comparator - is used to compare elements from the two collections. If null, then the objects in the collections are expected to implement the Comparable interface.

Method Detail

hasNext

public boolean hasNext()

Indicates whether there are any more elements to be returned.

next

public void next()

Moves this iterator object to refer to the next "pair" of objects.

Note that unlike the standard java.util.Iterator, this method does not return anything; it simply modifies which objects will be returned by the getLeft and getRight methods.

Throws:

java.util.NoSuchElementException - if this is called when hasNext would report false (this is standard iterator behaviour).

getLeft

public java.lang.Object getLeft()

Return an object from the "left" collection specified to this object's constructor. When the iterator has selected an element in the "right" collection for which there is no corresponding element in the left collection, then this will return null.

getRight

public java.lang.Object getRight()

See getLeft.