org.javimmutable.collections
Interface Cursor<T>

Type Parameters:
T -
All Superinterfaces:
Iterable<T>
All Known Subinterfaces:
CloseableCursor<T>
All Known Implementing Classes:
AbstractStartCursor, AbstractStartedCursor, EmptyStartedCursor, LazyCursor, MultiCursor, MultiTransformCursor, SequenceCursor, SingleValueCursor, TransformCursor, ValueFunctionCursor.Start

public interface Cursor<T>
extends Iterable<T>

Implemented by objects used to traverse persistent data structures. The iterators themselves must be immutable and always create a new iterator when start() or next() is called.


Nested Class Summary
static class Cursor.NotStartedException
          Thrown by hasValue() and getValue() if the cursor has not been started by calling next() yet.
static class Cursor.NoValueException
          Thrown by getValue() if the Cursor's hasValue() method returns false.
 
Method Summary
 T getValue()
          Return the value at the Cursor's position.
 boolean hasValue()
          Read-only method with no side effects that determines if the Cursor currently has a value.
 Cursor<T> next()
          Advances to the next (possibly first) value.
 Cursor<T> start()
          All Cursors are created in a pre-start position pointing "before" the first element.
 
Methods inherited from interface java.lang.Iterable
iterator
 

Method Detail

start

@Nonnull
Cursor<T> start()
All Cursors are created in a pre-start position pointing "before" the first element. Once traversal has begun a Cursor points to some element in the collection or to end ("after" the last element). The start() method advances to the first element if traversal has not yet started or does nothing if traversal has already started. Either next() or start() can be used to initiate a traversal however start() is safer since it can be used safely on already started cursors as well as not-started ones. This distinction is useful when passing a Cursor as parameter to a method that will traverse from the Cursor's current position forward and using start() prevents it from skipping the current value.

Must always return a non-null Cursor.

Returns:
Cursor for first position or this if already started

next

@Nonnull
Cursor<T> next()
Advances to the next (possibly first) value. Must always return a non-null Cursor. A newly created Cursor must always point to "before" the first value because next() (or start()) must always be called once before retrieving the first value. If the Cursor is already at the end of its sequence then it should return a Cursor that will always return false for hasValue().

Returns:
Cursor for next position

hasValue

boolean hasValue()
Read-only method with no side effects that determines if the Cursor currently has a value. Users of the Cursor will always call this after calling next() to see if they have reached the end of the sequence. If hasValue() returns true then next() will be called. If hasValue() returns false then next() must not be called.

Returns:
true iff getValue() can be called

getValue

T getValue()
Return the value at the Cursor's position. Only valid if a call to hasValue() would return true.

Returns:
current value
Throws:
IllegalStateException - if getValue() is not allowed for this iterator


Copyright © 2014 Burton Computer Corporation. All rights reserved.