CyclicIterator (TestHelpers 1.0-SNAPSHOT API)

Type Parameters:

E - the class of the elements to iterate over.

All Superinterfaces:

Iterator<E>

All Known Implementing Classes:

CollectionsExt.NonModifyingCyclicIterator, CyclicArrayList.CyclicArrayIterator
```
public interface CyclicIterator<E>
extends Iterator<E>
```
An iterator over a CyclicList. CyclicIterator corresponds with CyclicLists as Iterators or ListIterators do with Lists.

Version:

1.0

Author:

Ernst Reissner

See Also:

CyclicList, ListIterator

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`add(E obj)` Inserts the specified element into the underlying cyclic list (optional operation).
`void`	`addAll(List<? extends E> list)` Inserts the specified list into the underlying cyclic list (optional operation).
`double`	`dist(CyclicIterator<E> other)`
`boolean`	`equals(Object other)` Returns `false` if `other` is not an instance of `CyclicIterator`.
`CyclicList<E>`	`getCyclicList()` Returns the cyclic list to which this iterator points.
`int`	`getFirstIndex()` Returns the cursor of this iterator immediately after it has been created (if not modified since then which is currently not possible.).
`int`	`getIndex()` Returns the current cursor of this iterator.
`int`	`getNextIndexOf(E obj)` Returns the (non-negative) index of the next object returned by `next` which equals the given one, if possible; otherwise returns `-1`.
`boolean`	`hasNext()` Returns `true` if the iteration has more elements.
`boolean`	`hasPrev()` Returns `true` if this iterator has more elements when traversing the cyclic list in the reverse direction.
`E`	`next()` Returns the next element in the interation.
`E`	`previous()` Returns the previous element in the cyclic list.
`void`	`refresh()` Reinitialize this iterator without changing the cursor but such that all elements of the corresponding cyclic list may be accessed successively through `next()`.
`void`	`remove()` Removes from the underlying `CyclicList` the last element returned by `next` or `previous` (optional operation).
`boolean`	`retEquals(CyclicIterator<?> other)`
`void`	`set(E obj)` Replaces the last element returned by `next` or `previous` with the specified element (optional operation).
`void`	`setIndex(int index)` Sets the given index as cursor of this iterator.

Methods inherited from interface java.util.Iterator
forEachRemaining

- Method Detail
  - getFirstIndex
```
int getFirstIndex()
```
    Returns the cursor of this iterator immediately after it has been created (if not modified since then which is currently not possible.).
    
    Returns:
    
    the cursor of this iterator immediately after it has been created (if not modified since then).
    
    See Also:
    
    CyclicList.cyclicIterator(int)
  - getIndex
```
int getIndex()
```
    Returns the current cursor of this iterator.
    
    Returns:
    
    the current cursor of this iterator.
  - getCyclicList
```
CyclicList<E> getCyclicList()
```
    Returns the cyclic list to which this iterator points. Contract: cyclicList.cyclicIterator(int).getCyclicList() == cyclicList again.
    
    Returns:
    
    the cyclic list to which this iterator points. This may be empty but it may not be null.
    
    See Also:
    
    CyclicList.cyclicIterator(int)
  - hasNext
```
boolean hasNext()
```
    Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)
    
    Specified by:
    
    hasNext in interface Iterator<E>
    
    Returns:
    
    true if the iterator has more elements.
  - next
```
E next()
```
    Returns the next element in the interation. This method may be called repeatedly to iterate through the list, or intermixed with calls to previous to go back and forth. (Note that alternating calls to next and previous will return the same element repeatedly.)
    
    Specified by:
    
    next in interface Iterator<E>
    
    Returns:
    
    the next element in the interation.
    
    Throws:
    
    NoSuchElementException - iteration has no more elements.
  - hasPrev
```
boolean hasPrev()
```
    Returns true if this iterator has more elements when traversing the cyclic list in the reverse direction. (In other words, returns true if previous would return an element rather than throwing an exception.)
    
    Returns:
    
    true if the list iterator has more elements when traversing the list in the reverse direction.
  - previous
```
E previous()
```
    Returns the previous element in the cyclic list. This method may be called repeatedly to iterate through the list backwards, or intermixed with calls to next to go back and forth. (Note that alternating calls to next and previous will return the same element repeatedly.)
    
    Returns:
    
    the previous element in the list.
    
    Throws:
    
    NoSuchElementException - if the iteration has no previous element.
  - getNextIndexOf
```
int getNextIndexOf(E obj)
```
    Returns the (non-negative) index of the next object returned by next which equals the given one, if possible; otherwise returns -1.
    Parameters:
    
    obj - an object.
    
    Returns:
    the index minimal index ind in {0,...,this.list.size()-1} satisfying obj.equals(this.list.get(ind)) if possible;
    -1 if there is no such index.
  - setIndex
```
void setIndex(int index)
```
    Sets the given index as cursor of this iterator. Consider the case first that the underlying list getCyclicList() is not empty. Then it.setIndex(index); return it.getIndex(); returns index again up to it.getCyclicList().size(). For it.getCyclicList().isEmpty(), this method does not modify this iterator.
    
    Parameters:
    
    index - an arbitrary int value, which may also be negative.
  - add
```
void add(E obj)
```
    Inserts the specified element into the underlying cyclic list (optional operation). The element is inserted immediately before the next element that would be returned by next, if any, and after the next element that would be returned by previous, if any. (If the cyclic list is empty, the new element becomes the sole element on the cyclic list.)
    The new element is inserted before the implicit cursor: a subsequent call to next would be unaffected, and a subsequent call to previous would return the new element. (This call increases by one the value that would be returned by a call to nextIndex or previousIndex.)
    
    Parameters:
    
    obj - the element to be inserted.
    
    Throws:
    
    UnsupportedOperationException - if the add method is not supported by this iterator.
    
    ClassCastException - if the class of the specified element prevents it from being added to the underlying cyclic list.
    
    IllegalArgumentException - if some aspect of this element prevents it from being added to the underlying cyclic list.
    
    See Also:
    
    addAll(java.util.List<? extends E>)
  - addAll
```
void addAll(List<? extends E> list)
```
    Inserts the specified list into the underlying cyclic list (optional operation). The list is inserted immediately before the next element that would be returned by next, if any, and after the next element that would be returned by previous, if any. (If the cyclic list is empty, the new cyclic list comprises the given list.)
    The given list is inserted before the implicit cursor: a subsequent call to next would be unaffected, and a subsequent call to previous would return the given list in reversed order. (This call increases by list.size() the value that would be returned by a call to nextIndex or previousIndex.)
    If list.size() contains a single element e, addAll(list) is equivalent with add(e).
    
    Parameters:
    
    list - the list to be inserted.
    
    Throws:
    
    UnsupportedOperationException - if the add method is not supported by this iterator.
    
    ClassCastException - if the class of the an element in the specified list prevents it from being added to the underlying list.
    
    IllegalArgumentException - if some aspect of the an element in the specified list prevents it from being added to the underlying list.
    
    See Also:
    
    add(E)
  - set
```
void set(E obj)
```
    Replaces the last element returned by next or previous with the specified element (optional operation). This call can be made only if neither ListIterator.remove nor add have been called after the last call to next or previous.
    
    Parameters:
    
    obj - the element with which to replace the last element returned by next or previous.
    
    Throws:
    
    UnsupportedOperationException - if the set operation is not supported by this iterator.
    
    ClassCastException - if the class of the specified element prevents it from being added to this cyclic list.
    
    IllegalArgumentException - if some aspect of the specified element prevents it from being added to this list.
    
    IllegalStateException - if neither next nor previous have been called, or remove or add have been called after the last call to next or previous.
  - remove
```
void remove()
```
    Removes from the underlying CyclicList the last element returned by next or previous (optional operation). This method can be called only once per call to next or previous. It can be made only if add has not been called after the last call to next or previous.
    
    Specified by:
    
    remove in interface Iterator<E>
    
    Throws:
    
    UnsupportedOperationException - if the remove operation is not supported by this CyclicIterator.
    
    IllegalStateException - if neither next nor previous have been called, or remove or add have been called after the last call to next or previous.
  - refresh
```
void refresh()
```
    Reinitialize this iterator without changing the cursor but such that all elements of the corresponding cyclic list may be accessed successively through next(). On the other hand, previous() throws an exception.
  - retEquals
```
boolean retEquals(CyclicIterator<?> other)
```
  - equals
```
boolean equals(Object other)
```
    Returns false if other is not an instance of CyclicIterator. The implementation of this interface should not play a role.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    other - another Object.
    
    Returns:
    
    false if other is not an instance of CyclicIterator. The implementation of this interface should not play a role.
  - dist
```
double dist(CyclicIterator<E> other)
```

Interface CyclicIterator<E>

Method Summary

Methods inherited from interface java.util.Iterator

Method Detail

getFirstIndex

getIndex

getCyclicList

hasNext

next

hasPrev

previous

getNextIndexOf

setIndex

add

addAll

set

remove

refresh

retEquals

equals

dist