This iterator interface extends {@link java.util.Iterator}, and supports the standard hasNext and next methods. If finer control, including reverse iteration, is needed, see below.
Note: do not use the APIs described below *together* with the standard Java iterator methods next() and hasNext(). On any given iterator, use either the one or the other, but not both together. Otherwise, next/hasNext may exhibit incorrect behavior.
The FSIterator interface introduces the methods {@link #get()}, {@link #moveToNext()}, {@link #moveToPrevious()} methods. With these methods, retrieving thecurrent element (get) is a separate operation from moving the iterator (moveToNext and moveToPrevious. This makes the user's code less compact, but allows for finer control.
Specifically the get method is defined to return the same element that a call to next() would return, but does not advance the iterator.
Implementations of this interface are not required to be fail-fast. That is, if the iterator's collection is modified, the effects on the iterator are in general undefined. Some collections may handle this more gracefully than others, but in general, concurrent modification of the collection you're iterating over is a bad idea.
If the iterator is moved past the boundaries of the collection, the behavior of subsequent calls to {@link FSIterator#moveToNext() moveToNext()} or{@link FSIterator#moveToPrevious() moveToPrevious()} is undefined. For example, if a previouslyvalid iterator is invalidated by a call to {@link FSIterator#moveToNext() moveToNext()}, a subsequent call to {@link FSIterator#moveToPrevious() moveToPrevious()} is not guaranteed to setthe iterator back to the last element in the collection. Always use {@link FSIterator#moveToLast() moveToLast()} in such cases.
| |