Package com.complexible.common.collect

Interface SkippingIterator<T>

All Superinterfaces:

java.lang.AutoCloseable, CloseableIterator<T>, java.util.Iterator<T>, ResettableIterator<T>

All Known Subinterfaces:

PeekingSkippingIterator<T>

All Known Implementing Classes:

AbstractSkippingIterator, DelegatingSkippingIterator, MarkResetSkippingIterator, SpoolingMarkResetIterator

public interface SkippingIterator<T>
extends ResettableIterator<T>

Iterator over an ordered data source that is able to jump to a specific element (or the next greater after that). Iterator might return duplicate objects in which case skipping to an element might skip some occurrences of that element.

Since:

0.6.1

Version:

2.2.1

Author:

Pavel Klinov

Nested Class Summary

Nested classes/interfaces inherited from interface com.complexible.common.base.CloseableIterator

CloseableIterator.AbstractCloseableIterator<T>, CloseableIterator.DelegatingCloseableIterator<T>, CloseableIterator.EmptyCloseableIterator<T>

Field Summary

Fields

Modifier and Type	Field	Description
static long	UNKNOWN_SIZE

Method Summary

Modifier and Type	Method	Description
java.util.Comparator<T>	comparator()	Returns the comparator for this iterator that specifies the order in which the elements are returned.
long	estimatedSize()	Returns the estimated size of this iterator without advancing the iterator or UNKNOWN_SIZE if the estimate is not known.
T	skipTo(T theElement)	Returns the element which is equal or greater to theElement based on the ordering of the elements in the underlying data source, i.e., for two elements A, B s.t.
default T	skipTo(T theElement, T theBound)	Same contract as skipTo(Object) but skipping is bounded: if the next element that is greater than or equal to the target is greater than the bound, the method returns null.

Methods inherited from interface com.complexible.common.base.CloseableIterator

close

Methods inherited from interface java.util.Iterator

forEachRemaining, hasNext, next, remove

Methods inherited from interface com.complexible.common.collect.ResettableIterator

reset

Field Detail

UNKNOWN_SIZE

static final long UNKNOWN_SIZE

See Also:

Constant Field Values

Method Detail

skipTo

T skipTo(T theElement)

Returns the element which is equal or greater to theElement based on the ordering of the elements in the underlying data source, i.e., for two elements A, B s.t. B comes after A during iteration, theComparator should return A <= B. Note that skips are always in the forward direction. if theElement compares to less than the last returned element (or less than the bounding start of the iterator), then no skip will occur, and the returned value is the same as if `next()` was called.

Returns:

the smallest element A s.t. A <= theElement, if theElement > last seen element, or the output of next() if not.

skipTo

default T skipTo(T theElement,
                 T theBound)

Same contract as skipTo(Object) but skipping is bounded: if the next element that is greater than or equal to the target is greater than the bound, the method returns null. Implementations are free to not move their internal cursor beyond the bound which may enable them to make less work or skip IO. However, they must maintain their internal state to ensure that the smallest element that is greater than theBound is not consumed and is returned for the next Iterator.next() call.

Parameters:

theElement - the target

theBound - the bound. null means no upper bound.

Returns:

the smallest element that's greater than or equal to the target but not greater than the bound.

comparator

java.util.Comparator<T> comparator()

Returns the comparator for this iterator that specifies the order in which the elements are returned.

estimatedSize

long estimatedSize()

Returns the estimated size of this iterator without advancing the iterator or UNKNOWN_SIZE if the estimate is not known. The estimate is for the whole iterator and will not change after the iterator is advanced. There is no guarantee about the accuracy of the estimate.