net.sf.staccatocommons.iterators.thriter
Interface Thriter<A>

Type Parameters:

A - the type of elements retrieved by this Thriter

All Known Subinterfaces:

Thriterator<A>

All Known Implementing Classes:

AbstractThriterator, AdvanceThriterator, AppendThriterator, ArrayThriterator, CharSequenceThriterator, DelayedAppendIterator, DelayedPrependIterator, DelayedSingleIterator, EmptyThriterator, EnumerationIterator, IndexedThriterator, IteratorThriterator, NextThriterator, PrependThriterator, SingleThriterator, UpdateCurrentThriterator

public interface Thriter<A>

A Thriter - acronym for Three-messages Iterator - is an object that can traverse elements of type A from a collection-like object, much like an Iterator does, but using three messages instead of two, enabling new lazy features. Such messages are hasNext(), advanceNext() and current():

• hasNext() is completely equivalent to Iterator#hasNext() , this message just polls if the iterator has more elements. It must be side-effect free, and its result must be constant as long as the thriter is not advanced.
• advanceNext() advances the iterator to its next element, but it does not return it. Like Iterator#next(), it must throw a no NoSuchElementException if the iterator has reached its end
• current() returns the element at the actual position. This method should return the same element as long as the thriter is not advanced, but the result of evaluating it if the thriter was never advanced is undefined. Lazy thriters should implementing the actual processing here

For example,

 while (thriter.hasNext) {
   thriter.advanceNext();
   A elem = thriter.current();
 }
 

Although normal iteration on thriters is more complex that in Iterators, the power of Thriters lays if that it allows to perform special lazy iterations that would be otherwise impossible with an plain two-messages iterator.

For example, lets assume that a Thriter thriter can retrieve two elements, and that its first element is bottom - that is, it will never return normally, for example, by throwing an exception or by falling in a infinite loop. Then, the second element of the thriter is an actual value - accessing it would return normally. In such scenario, the following successfully obtains the second element of the thriter:

 thriter.advance();
 thriter.advance();
 thriter.current();
 

However, the same behavior is impossible to implement using a Iterator, as in order to access the n element, it is necessary to access the n-1 element.

Author:

flbulgarelli

See Also:

Thriterator, AbstractThriterator

Method Summary

void	advanceNext() Advances to the thriter to the position of the next element.
A	current() Answers element at the current position of this Thriter.
Thunk<A>	delayedCurrent() Answers a Thunk that, when evaluated through Thunk.value(), will return the current element of this Thriter at the time of being delayedCurrent() sent.
Thunk<A>	delayedNext() Advances this thriter and the returns delayedCurrent()
boolean	hasNext() Answers if the thriter has more elements, that is, if sending advanceNext() would not result in a NoSuchElementException

Method Detail

hasNext

@SideEffectFree
boolean hasNext()

Answers if the thriter has more elements, that is, if sending advanceNext() would not result in a NoSuchElementException

Returns:

if the Thriter has more elements

advanceNext

void advanceNext()
                 throws NoSuchElementException

Advances to the thriter to the position of the next element.

Throws:

NoSuchElementException - if there are no more elements

current

A current()

Answers element at the current position of this Thriter. Result of this method if advanceNext() was never evaluated before is undefined.

Returns:

the current element

delayedCurrent

@NonNull
Thunk<A> delayedCurrent()

Answers a Thunk that, when evaluated through Thunk.value(), will return the current element of this Thriter at the time of being delayedCurrent() sent. This means, that the value of the returned thunk must must always equals, even if this Thriter was advanced later.

Returns:

a Thunk tha provides current() at the time of this message being sent.

delayedNext

@NonNull
Thunk<A> delayedNext()

Advances this thriter and the returns delayedCurrent()

Returns:

delayedCurrent()