28.7 Iterators

Iterators provide a possibility to loop over the elements of a (countable) collection C or a list list, without repetition. For many collections C, an iterator of C need not store all elements of C, for example it is possible to construct an iterator of some infinite domains, such as the field of rational numbers.

Iterator returns a mutable iterator iter for its argument. If this is a list list (which may contain holes), then iter iterates over the elements (but not the holes) of list in the same order (see IteratorList for details). If this is a collection C but not a list then iter iterates over the elements of C in an unspecified order, which may change for repeated calls of Iterator. Because iterators returned by Iterator are mutable (see Mutability and Copyability), each call of Iterator for the same argument returns a new iterator. Therefore Iterator is not an attribute (see Attributes).

The only operations for iterators are IsDoneIterator, NextIterator, and ShallowCopy. In particular, it is only possible to access the next element of the iterator with NextIterator if there is one, and this can be checked with IsDoneIterator (see NextIterator). For an iterator iter, ShallowCopy( iter ) is a mutable iterator new that iterates over the remaining elements independent of iter; the results of IsDoneIterator for iter and new are equal, and if iter is mutable then also the results of NextIterator for iter and new are equal; note that = is not defined for iterators, so the equality of two iterators cannot be checked with =.

When Iterator is called for a mutable collection C then it is not defined whether iter rescpects changes to C occurring after the construction of iter, except if the documentation explicitly promises a certain behaviour. The latter is the case if the argument is a mutable list list (see IteratorList for subtleties in this case).

It is possible to have for-loops run over mutable iterators instead of lists.

In some situations, one can construct iterators with a special succession of elements, see IteratorByBasis for the possibility to loop over the elements of a vector space w.r.t. a given basis.

For lists, Iterator is implemented by IteratorList( list ). For collections that are not lists, the default method is IteratorList( Enumerator( C ) ). Better methods depending on C should be provided if possible.

For random access to the elements of a (possibly infinite) collection, enumerators are used. See Enumerators for the facility to compute a list from C, which provides a (partial) mapping from C to the positive integers.

gap> iter:= Iterator( GF(5) );
<iterator>
gap> l:= [];;
gap> for i in iter do Add( l, i ); od; l;
[ 0*Z(5), Z(5)^0, Z(5), Z(5)^2, Z(5)^3 ]
gap> iter:= Iterator( [ 1, 2, 3, 4 ] );;  l:= [];;
gap> for i in iter do
>      new:= ShallowCopy( iter );
>      for j in new do Add( l, j ); od;
>    od; l;
[ 2, 3, 4, 3, 4, 4 ]

IteratorSorted returns a mutable iterator. The argument must be a collection C or a list list that is not necessarily dense but whose elements lie in the same family (see Families). It loops over the different elements in sorted order.

For collections C that are not lists, the generic method is IteratorList( EnumeratorSorted( C ) ).

Every iterator lies in the category IsIterator.

If iter is an iterator for the list or collection C then IsDoneIterator( iter ) is true if all elements of C have been returned already by NextIterator( iter ), and false otherwise.

Let iter be a mutable iterator for the list or collection C. If IsDoneIterator( iter ) is false then NextIterator is applicable to iter, and the result is the next element of C, according to the succession defined by iter.

If IsDoneIterator( iter ) is true then it is not defined what happens if NextIterator is called for iter; that is, it may happen that an error is signalled or that something meaningless is returned, or even that GAP crashes.

IteratorList returns a new iterator that allows iteration over the elements of the list list (which may have holes) in the same order.

If list is mutable then it is in principle possible to change list after the call of IteratorList. In this case all changes concerning positions that have not yet been reached in the iteration will also affect the iterator. For example, if list is enlarged then the iterator will iterate also over the new elements at the end of the changed list.

Note that changes of list will also affect all shallow copies of list.

is a mutable iterator for the collection [ elm ] that consists of exactly one element elm (see IsTrivial).

gap> iter:= Iterator( [ 1, 2, 3, 4 ] );
<iterator>
gap> sum:= 0;;
gap> while not IsDoneIterator( iter ) do
>      sum:= sum + NextIterator( iter );
>    od;
gap> IsDoneIterator( iter ); sum;
true
10
gap> ir:= Iterator( Rationals );;
gap> l:= [];; for i in [1..20] do Add( l, NextIterator( ir ) ); od; l;
[ 0, 1, -1, 1/2, 2, -1/2, -2, 1/3, 2/3, 3/2, 3, -1/3, -2/3, -3/2, -3, 1/4,
  3/4, 4/3, 4, -1/4 ]
gap> for i in ir do
>      if DenominatorRat( i ) > 10 then break; fi;
>    od;
gap> i;
1/11

[Top] [Previous] [Up] [Index]