Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

ClassIterator

class Iterator( collection, [position] )

Indirect pointer to sequences. more...


Member list

Constructor
init Initialize the iterator
Methods
clone Returns an instance of this iterator pointing to the same item.
equal Check if this iterator is equal to the provided item.
erase Erase current item in the underlying sequence.
find Moves this iterator on the searched item.
getOrigin Returns the underlying sequence.
hasCurrent Check if the iterator is valid and can be used to access the underlying collection.
hasNext Check if the iterator is valid and a Iterator.next operation would still leave it valid.
hasPrev Check if the iterator is valid and a Iterator.prev operation would still leave it valid.
insert Insert an item, or a pair of key values, in an underlying sequence.
key Retreives the current key in the collection.
next Advance the iterator.
prev Move the iterator back.
value Retreives the current item in the collection.

Detailed description

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.


Class methods

init()

Initialize the iterator

Iterator.init( collection, [position] )
collection

The collection on which to iterate.

position

Indicator for start position.

The iterator is normally created at the begin of the sequence. If items in the collection can be directly accessed (i.e. if the collection is an array or a string), the position parameter can be any valid index.

Otherwise, position can be 0 (the default) or -1. If it's -1, an iterator pointing to the last element of the collection will be returned.

clone()

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

Iterator.clone( )
Returns:

A 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.

Returns:

True 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( )
Raises:
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.

Returns:

true if the key was found, false otheriwse.

Raises:
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.

In 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.

getOrigin()

Returns the underlying sequence.

Iterator.getOrigin( )
Returns:

The sequence being pointed by this iterator.

hasCurrent()

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

Iterator.hasCurrent( )
Returns:

true 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( )
Returns:

true 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( )
Returns:

true 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.

Raises:
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.find.

key()

Retreives the current key in the collection.

Iterator.key( )
Returns:

The current key.

Raises:
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( )
Returns:

true 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( )
Returns:

true 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.

Returns:

The current item.

Raises:
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.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0