Package eu.simuline.util

Interface CyclicIterator<E>

Type Parameters:

E - the class of the elements to iterate over.

All Superinterfaces:

java.util.Iterator<E>

All Known Implementing Classes:

CollectionsExt.NonModifyingCyclicIterator, CyclicArrayList.CyclicArrayIterator

public interface CyclicIterator<E>
extends java.util.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

Modifier and Type	Method	Description
void	add(E obj)	Inserts the specified element into the underlying cyclic list (optional operation).
void	addAll(java.util.List<? extends E> list)	Inserts the specified list into the underlying cyclic list (optional operation).
double	dist(CyclicIterator<E> other)
boolean	equals(java.lang.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 java.util.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 java.util.Iterator<E>

Returns:

the next element in the interation.

Throws:

java.util.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:

java.util.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:

java.lang.UnsupportedOperationException - if the add method is not supported by this iterator.

java.lang.ClassCastException - if the class of the specified element prevents it from being added to the underlying cyclic list.

java.lang.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(java.util.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:

java.lang.UnsupportedOperationException - if the add method is not supported by this iterator.

java.lang.ClassCastException - if the class of the an element in the specified list prevents it from being added to the underlying list.

java.lang.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:

java.lang.UnsupportedOperationException - if the set operation is not supported by this iterator.

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this cyclic list.

java.lang.IllegalArgumentException - if some aspect of the specified element prevents it from being added to this list.

java.lang.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 java.util.Iterator<E>

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this CyclicIterator.

java.lang.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(java.lang.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 java.lang.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)