byucc.jhdl.synth.graph
Interface GenericIterator

All Known Subinterfaces:

IndexedIterator, IndexedVertexIterator, VertexIterator

All Known Implementing Classes:

SubsetIterator, VectorIterator, VertexVectorIterator

public interface GenericIterator

An object that implements the GenericIterator interface guarantees sequential access to a series of elements, in both forward and backward direction. This interface is similar to Java's Enumeration except that it allows access in both directions and it is more friendly for use in for loops.

Here's an example of using a GenericIterator in a for loop:

   // Assuming list is a valid object implementing GenericIterator
   for (list.first(); list.isValid(); list.next()) {
       Object element = list.getElt();
       // Operate on element ...
   }

Note: I originally wrote this interface and named it Iterator before I learned that Java2 will have an Iterator interface in java.util. This interface is actually most like ListIterator in java.util. I've read the documentation for java.util.ListIterator and I don't like it for a few reasons:

1. The next() and previous() methods move the iterator as well as fetch an item. This is annoying in that a single API call is performing two distinct functions. This makes it impossible for the user to perform one of those operations without the other. This is the same problem that Enumeration has. One ugly effect of this is that for loops end up with an empty increment part and the actual increment (the call to next) is buried in the body of the loop.
2. Although you can move forward and backward there is no single call to move the iterator immediately to the beginning or the end of the list. It starts out at the beginning and if you ever want it to be there again you have to call previous() several times or make a new ListIterator.
3. The nextIndex and prevIndex methods don't make a lot of sense to me. These methods would make sense if there were also methods for size() and moveTo(int index). Without these, the two index methods seem thrown in without thought.

All that being said, java.util.Iterator does do a couple of nice things. It has fairly good names for testing terminal conditions, (I prefer it.hasNext() to jhdl.base's !it.atEnd()). Unfortunately, I can't use hasNext() and hasPrev() because I want a condition that will work in a for loop, (hasNext would stop one too soon). Also, they finally posed at least a partial solution to the big problem from Enumeration that deleting an element during iteration had no defined semantics.

So, enough of my ranting and raving. I only include it here to explain why I am using my own interface even though it is similar to one put out by Sun. (Not to mention that we are still using Java 1.1 for JHDL so we couldn't use java.util.Iterator right now anyway). I will be nice enough to avoid a potential class name conflict by renaming this interface GenericIterator.

Author:

Carl Worth

Method Summary

boolean	deleteElt() Delete the object currently pointed at by the iterator.
GenericIterator	first() Move this iterator's "pointer" to the first element in the series.
java.lang.Object	getElt() Retrieves the object currently pointed at by the iterator.
boolean	isValid() Checks if the iterator currently points to a valid item in the series.
GenericIterator	last() Move this iterator's "pointer" to the last element in the series.
boolean	moveTo(java.lang.Object elt) Moves the iterator to the specified element.
GenericIterator	next() Moves the iterator to the next element in the series.
GenericIterator	prev() Moves the iterator to the previous element in the series.

Method Detail

first

public GenericIterator first()

Move this iterator's "pointer" to the first element in the series.

Returns:

this GenericIterator, (suitable for chaining)

last

public GenericIterator last()

Move this iterator's "pointer" to the last element in the series.

Returns:

this GenericIterator, (suitable for chaining)

isValid

public boolean isValid()

Checks if the iterator currently points to a valid item in the series. This method will return false after calling next() when on the last item or after calling prev() when on the first item.

Returns:

true if iterator points to a valid item, false otherwise.

next

public GenericIterator next()

Moves the iterator to the next element in the series.

Returns:

this GenericIterator, (suitable for chaining)

prev

public GenericIterator prev()

Moves the iterator to the previous element in the series.

Returns:

this GenericIterator, (suitable for chaining)

moveTo

public boolean moveTo(java.lang.Object elt)

Moves the iterator to the specified element. The equality check to determine if elt is in the series uses the Object.equals() method which may be overriden.

Returns:

true if pointer was moved to elt, false if the given element is not in the series. (If false then the current pointer's position is undefined. It may be invalid).

getElt

public java.lang.Object getElt()

Retrieves the object currently pointed at by the iterator.

Returns:

the current object in the series.

deleteElt

public boolean deleteElt()

Delete the object currently pointed at by the iterator. After calling delete, this iterator's current "pointer" will be at an undefined position, (it may even be invalid). However, calling next() will move it to the element originally after the deleted element and calling prev() will move it to the element originally before element.

Also Note: Any modifications of the series of elements, (ie. deletes or modifications), other than through this iterator may cause undefined effects on the state of this iterator.

Returns:

true if the object was deleted false if the current pointer is not valid.