Package org.plumelib.util

Class OrderedPairIterator<T extends @Nullable Object>

java.lang.Object

org.plumelib.util.OrderedPairIterator<T>

Type Parameters:

T - the element type of each component iterator; this OrderedPairIterator has elements of type MPair<T,T>

All Implemented Interfaces:

Iterator<MPair<@Nullable T,@Nullable T>>

public class OrderedPairIterator<T extends @Nullable Object>
extends Object
implements Iterator<MPair<@Nullable T,@Nullable T>>

Given two sorted iterators, this class returns a new iterator that pairs equal elements of the inputs, according to the sort order or the given comparator. If an element has no equal element in the other iterator, then the element is paired with null.

For example, suppose that the inputs are

   [1, 2, 3, 5] and
   [1, 3, 5, 7, 9].
 

Then the output is

   [(1,1), (2,null), (3,3), (5,5), (null,7), (null, 9)].
 

(This operation is similar to, but not the same as, the operation called "zipping".)

In some cases this is just the right abstraction. But in some cases it's appropriate to use set intersection/difference instead.

Field Summary

Fields

Modifier and Type	Field	Description
(package private) @Nullable Comparator<? super T>	comparator	The comparator to be used to compare elements from the two iterators, to determine whether they match.
(package private) Iterator<T>	itor1	The iterator for first elements of pairs.
(package private) Iterator<T>	itor2	The iterator for second elements of pairs.
(package private) @Nullable T	next1	The next element to be read by itor1.
(package private) @Nullable T	next2	The next element to be read by itor2.

Constructor Summary

Constructors

Constructor	Description
OrderedPairIterator(Iterator<T> itor1, Iterator<T> itor2)	Create an iterator that returns pairs, where each pair contains has an element from each iterator and the two elements are equal.
OrderedPairIterator(Iterator<T> itor1, Iterator<T> itor2, Comparator<T> comparator)	Create an iterator that returns pairs, where each pair contains has an element from each iterator and the two elements are equal according to the comparator.

Method Summary

Modifier and Type	Method	Description
boolean	hasNext()
MPair<@Nullable T,@Nullable T>	next()
void	remove()
private MPair<@Nullable T,@Nullable T>	return1()	Returns an element of the first iterator, paired with null.
private MPair<@Nullable T,@Nullable T>	return2()	Returns a pair of null and an element of the second iterator.
private MPair<@Nullable T,@Nullable T>	returnboth()	Returns a pair containing an element from each iterator.
private void	setnext1()	Set the next1 variable.
private void	setnext2()	Set the next2 variable.

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

itor1

Iterator<T extends @Nullable Object> itor1

The iterator for first elements of pairs.

itor2

Iterator<T extends @Nullable Object> itor2

The iterator for second elements of pairs.

next1

@Nullable T extends @Nullable Object next1

The next element to be read by itor1.

next2

@Nullable T extends @Nullable Object next2

The next element to be read by itor2.

comparator

@Nullable Comparator<? super T extends @Nullable Object> comparator

The comparator to be used to compare elements from the two iterators, to determine whether they match. Null to use the natural comparison.

Constructor Details

OrderedPairIterator

public OrderedPairIterator(Iterator<T> itor1,
 Iterator<T> itor2)

Create an iterator that returns pairs, where each pair contains has an element from each iterator and the two elements are equal.

Parameters:

itor1 - iterator for first elements of pairs

itor2 - iterator for second elements of pairs

OrderedPairIterator

public OrderedPairIterator(Iterator<T> itor1,
 Iterator<T> itor2,
 Comparator<T> comparator)

Create an iterator that returns pairs, where each pair contains has an element from each iterator and the two elements are equal according to the comparator.

Parameters:

itor1 - iterator for first elements of pairs

itor2 - iterator for second elements of pairs

comparator - determines whether two elements are equal and should be paired together

Method Details

setnext1

@RequiresNonNull("itor1")
private void setnext1(@GuardSatisfied @UnknownInitialization OrderedPairIterator<T extends @Nullable Object> this)

Set the next1 variable.

setnext2

@RequiresNonNull("itor2")
private void setnext2(@GuardSatisfied @UnknownInitialization OrderedPairIterator<T extends @Nullable Object> this)

Set the next2 variable.

hasNext

public boolean hasNext(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Specified by:

hasNext in interface Iterator<T extends @Nullable Object>

return1

private MPair<@Nullable T,@Nullable T> return1(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Returns an element of the first iterator, paired with null.

Returns:

an element of the first iterator, paired with null

return2

private MPair<@Nullable T,@Nullable T> return2(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Returns a pair of null and an element of the second iterator.

Returns:

a pair of null and an element of the second iterator

returnboth

private MPair<@Nullable T,@Nullable T> returnboth(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Returns a pair containing an element from each iterator.

Returns:

a pair containing an element from each iterator

next

public MPair<@Nullable T,@Nullable T> next(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Specified by:

next in interface Iterator<T extends @Nullable Object>

remove

public void remove(@GuardSatisfied OrderedPairIterator<T extends @Nullable Object> this)

Specified by:

remove in interface Iterator<T extends @Nullable Object>