Iterator

An Iterator is an object that allows you to visit each element of a Collection using a consistent interface for all types of collections. You can never instantiate an Iterator directly (in other words, you can't use the new operator to create an Iterator); instead, you create an Iterator by calling a Collection object's createIterator() method, which creates an iterator customized for that specific type of collection.

When you create an Iterator via a Collection's createIterator() method, the Iterator refers to a "snapshot" of the collection, and is initialized so that the first call to getNext() will return the first element of the collection. The Iterator uses a snapshot of the collection to ensure that changes made to the collection after creating the Iterator do not affect the iteration.

Iterator methods

getCurKey()

Returns the key for the current item in the iteration. For List and Vector objects, this returns the index of the current value; for LookupTable objects, this returns the key. Throws an error ("index out of range") if the iteration has not been started yet (that is, getNext() has never been called on this Iterator) or has moved past the last item.

getCurVal()

Returns the value of the current item in the iteration (this is the same value that the most recent call to getNext() returned). Throws an error ("index out of range") if the iteration has not been started yet or has moved past the last item.

getNext()

Returns the next element of the collection. The order in which the iterator returns the collection's elements varies by the collection type:

Each time you call getNext(), the iterator updates its internal state to refer to the next element of the collection, so the next call will return the next item. When you first create an Iterator (by calling a Collection object's createIterator() method), the Iterator is initialized so that the first call to getNext() will return the first element of the collection.

After all of the collection's elements have been exhausted, calling getNext() will cause an error ("out of bounds") to be thrown.

isNextAvailable()

Returns true if calling getNext() will yield a valid item, nil if not. You can call this prior to calling getNext() to ensure that getNext() will not throw an error.

resetIterator()

Resets the iteration to its first element. After calling this method, the next call to getNext() will yield the first element of the collection.