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. |
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.