1.7.2Class Iterator

Indirect pointer to sequences.

Class Iterator( collection, [atEnd] )
collection The collection on which to iterate.
atEnd Indicator for start position.

An iterator is an object meant to point to a certain position in a collection (array, dictionary, string, or eventually user defined types), and to access iteratively the elements in that collection.

Iterators may be used to alter a collection by removing the item they are pointing to, or by changing its value. They can be stored to be used at a later moment, or they can be passed as parameters. Most notably, they hide the nature of the underlying collection, so that they can be used as an abstraction layer to access underlying data, one item at a time.

Altering the collection may cause an iterator to become invalid; only performing write operations through an iterator it is possible to guarantee that it will stay valid after the modify. A test for iterator validity is performed on each operation, and in case the iterator is not found valid anymore, an error is raised.

Iterators supports equality tests and provide an equal() method. Two iterators pointing to the same element in the same collection are considered equal; so it is possible to iterate through all the items between a start and an end.

Initialization

The iterator is normally created at the begin of the sequence. If items in the collection can be directly accessed

If position is given and true, the iterator starts from the end of the sequence (that is, pointing to the last valid element in the sequence), otherwise it points at the first valid element.

Methods
cloneReturns an instance of this iterator pointing to the same item.
equalCheck if this iterator is equal to the provided item.
eraseErase current item in the underlying sequence.
findMoves this iterator on the searched item.
hasCurrentCheck if the iterator is valid and can be used to access the underlying collection.
hasNextCheck if the iterator is valid and a Iterator.next operation would still leave it valid.
hasPrevCheck if the iterator is valid and a Iterator.prev operation would still leave it valid.
insertInsert an item, or a pair of key values, in an underlying sequence.
keyRetreives the current key in the collection.
nextAdvance the iterator.
prevMove the iterator back.
valueRetreives the current item in the collection.

Methods

clone

Returns an instance of this iterator pointing to the same item.

Iterator.clone()
ReturnA new copy of this iterator.

Creates an iterator equivalent to this one. In this way, it is possible to record a previous position and use it later. Using a normal assignment wouldn't work, as the assignand would just be given the same iterator, and its value would change accordingly with the other image of the iterator.

equal

Check if this iterator is equal to the provided item.

Iterator.equal( item )
item The item to which this iterator must be compared.
ReturnTrue if the item matches this iterator.

This method overrides the FBOM equal method, and overloads the equality check of the VM.

erase

Erase current item in the underlying sequence.

Iterator.erase()
Raise
AccessError if the iterator is invalid.

If the iterator is valid, this method removes current item. The iterator is moved to the very next item in the collection, and this may invalidate it if the removed element was the last one. To remove element while performing a scanning from the last element to the first one, remember to call the prev() method after every remove(); in forward scans, a successful remove() implies that the caller must not call next() to continue the scan.

find

Moves this iterator on the searched item.

Iterator.find( key )
key the key to be searched.
Returntrue if the key was found, false otheriwse.
Raise
AccessError if the iterator is invalid or if the sequence doesn't provide keys.

This method searches for an key in the underlying sequence, provided it offers search keys support. This is the case of the various dictionaries.

This search is optimizied so that the subtree below the current position of the iterator is searched first. If the iterator is pointing to an item that matches the required key, this method returns immediately.

After a succesful search, the iterator is moved to the position of the searched item.

After a failed search, the iterator is moved to the smallest item in the sequence greater than the desired key; it's the best position for an insertion of the searched key.

For example, to traverse all the items in a dictionary starting with 'C', the following code can be used:


   dict = [ "Alpha" => 1, "Beta" => 2, "Charlie" => 3, "Columbus" => 4, "Delta" => 5 ]
   iter = Iterator( dict )

   iter.find( "C" )  // we don't care if it succeeds
   while iter.hasCurrent() and iter.key()[0] == "C"
      > iter.key(), " => ", iter.value()
      iter.next()
   end

Also, a failed search gives anyhow a useful hint position for a subsequent insertion, which may avoid performing the search again.

hasCurrent

Check if the iterator is valid and can be used to access the underlying collection.

Iterator.hasCurrent()
Returntrue if the iterator is valid and can be used to access a current item.

hasNext

Check if the iterator is valid and a Iterator.next operation would still leave it valid.

Iterator.hasNext()
Returntrue if there is an item past to the current one.

hasPrev

Check if the iterator is valid and a Iterator.prev operation would still leave it valid.

Iterator.hasPrev()
Returntrue if there is an item before to the current one.

insert

Insert an item, or a pair of key values, in an underlying sequence.

Iterator.insert( key, [value] )
key Item to be inserted (or key, if the underlying sequence is keyed).
value A value associated with the key.
Raise
AccessError if the iterator is invalid.

Inserts an item at current position. In case the underlying sequence is an ordered sequence of key-value pairs, a correct position for insertion is first searched, and then the iterator is moved to the position of the inserted key.

In this second case, if the iterator already points to a valid position for insertion of the given key, the search step is skipped.

See also: Iterator.

key

Retreives the current key in the collection.

Iterator.key()
ReturnThe current key.
Raise
AccessError if the iterator is not valid, or if the collection has not keys.

If this iterator is valid and is pointing to a collection that provides key ordering (i.e. a dictionary), it returns the current key; otherwise, it raises an AccessError.

next

Advance the iterator.

Iterator.next()
Returntrue if the iterator is still valid after next() has been completed.

Moves the iterator to the next item in the collection. If the iterator is not valid anymore, or if the current element was the last in the collection, the method returns false. If the iterator has successfully moved, it returns true.

prev

Move the iterator back.

Iterator.prev()
Returntrue if the iterator is still valid after prev() has been completed.

Moves the iterator to the previous item in the collection. If the iterator is not valid anymore, or if the current element was the first in the collection, the method returns false. If the iterator has successfully moved, it returns true.

value

Retreives the current item in the collection.

Iterator.value( [subst] )
subst New value for the current item.
ReturnThe current item.
Raise
AccessError if the iterator is not valid.

If the iterator is valid, the method returns the value of the item being currently pointed by the iterator.

If a parameter subst is given, the current value in the sequence is changed to substs.

Made with http://www.falconpl.org