Defining Iterators

Sather - A Language Tutorial
Prev | Chapter 3. Loops and Iterators | Next

# 3.2. Defining Iterators

## 3.2.1. yield statements

Iterator definitions are similar to routine definitions, except that we need to indicate when control should be transferred back to the calling point. In a routine, this transfer of control is indicated by a `return` statement, which terminates the routine. An iterator, however, can return control in two different ways. It can either

- Temporarily yield control to the callig point, ready to continue the next time it is encountered. This yield of control is done by a `yield` statement

- Permanently yield control to the calling loop, terminating the loop in the process. This termination of the enclosing loop is achieved by a `quit` statemen or by reaching the end of the iteratort.

The `yield` must return a value (of the appropriate type), if the iterator has a return value.

    range!(min, max:INT):INT is
       i:INT := min;
       loop until!(i > max);
          yield i;
          i := i + 1;
       end;
    end;

This iterator can be used to add up all the numbers in a particular integer range

    sum: INT := 0;
    loop
       sum := sum + range!(1,10);
    end;

## 3.2.2. Explicitly leaving an iterator using quit

When an iterator has yielded as many times as needed, it can either reach the end of it's statement list or explicitly call a quit statement. quit statements are used to terminate loops and may only appear in iterator definitions. No value is returned from an iterator when it quits. No statements may follow a `quit` statement in a statement list. The following definition of 'range!' is equivalent to the preceeding definition:

    range!(min, max:INT):INT is
       x:INT := min;
       loop
          if x > max then
             quit;
          end;
          yield x;
          x := x + 1;
       end;
    end;

## 3.2.3. Control flow within an iterator

The following figures illustrate the control flow between an interator and its calling loop.

When the iterator is first called, control goes into the iterator and then returns to the outer loop, when the iterator yields in step [7]

After the first yield, control continues in the outer loop until the iterator is encountered again in step [11] and control is again transferred to the iterator, right after the point of the yield, in step [12]

The above sequence will continue until the `if` statement is true and the `quit` statement is encountered in the iterator. Control is then transferred to the end of the enclosing loop. The iterator calling context keeps track of the internal state of the iterator from the last yield.

## 3.2.4. The once argument mode

One problem with the above definition of `'range!'` is that the arguments to the function will be evaluated each time through the loop. Consider the following loop

    sum:INT := 0;
    max:INT := 5;
    loop
       sum := sum + range!(3,max);
       max := max+2;
    end;

This, somewhat silly, example will go into an infinite loop, since the argument `'max'` increases each time through the loop.

Iterator argument are hot by default. This means that the arguments will be re-evaluated and passed to the iterator each time through the loop. When the arguments to the iterator are constant, it is not important whether they are re evaluated or not. However, in many cases it is important to ensure that the argument is only evaluated the first time through the loop.

This happens to `once-`arguments. Arguments which are marked with the mode '`once` are only evaluated the first time they are encountered during a loop execution. Thus, the correct definition of the 'range' iterator is:

    range!(once min, once max:INT):INT is
       i:INT := min;
       loop
          until!(i > max);
          yield i
          i := i + 1;
       end;
    end;

Note that `'once'` arguments are only marked at the point of definition, not at the point of call. Thus, invoking the loop will look the same as before

    sum:INT := 0;
    loop
       sum := sum + range!(3,5);
    end;

The `'self'` parameter (i.e. the object on which the iterator is being called) is always a once parameter.

    i:INT := 5;
    loop
       #OUT + i.upto!(11)! + ' ';
       i := 1;
    end;
    -- The above loop prints out 5 6 7 8 9 10 11

In the above example, though the value of `'i'` changes the second time through the loop, the change is ignored - the first value of `'i'` is used.

The following more complex example will sum up some of the elements of the first row although the variable `row` will contain different rows in consecutive loop iterations.

    loop  -- Sum up some of the elements of the first row!
       row := matrix.row!;
       sum := sum + row.elt!;
       -- row is only evaluated at the first iteration!
    end;

## 3.2.5. out and inout argument modes

Yield causes assignment to `out` and `inout` rguments in the caller i.e. these arguments are assigned each time when the iterator yields..

    range!(once min, once max:INT, out val:INT) is
       i:INT := min;
       loop until!(i > max);
          val := i;
          yield;
          i := i + 1;
       end;
    end;

Which may be used by:

    sum:INT := 0;
    loop
       res:INT;
       range2!(3,5, out res);
       sum := sum + res;
    end;
    #OUT + sum + '\n'; -- Prints out 12

Note that no assignment to `out` and `inout` arguments takes place when an iterator quits.

## 3.2.6. pre and post conditions in iterators

The behavior of pre- and post- conditions in iterator definitions is a natural extension of their behavior in routine definitions. The `pre` clause must be true each time the iterator is called and the `post` clause must be true each time it yields. The `post` clause is not evaluated when an iterator quits.

## 3.2.7. Argument evaluation in iterators

At a more technical level, when an iterator is first called in a loop, the expressions for `self` and for each `once` argument are evaluated left to right. Then the expressions for arguments which are not `once` (`in` or `inout` before the call, `out` or `inout` after the call) are evaluated left to right. On subsequent calls, only the expressions for arguments which are not `once` are re-evaluated. `self` and any `once` arguments retain their earlier values.

## 3.2.8. Points to note

## Iterator usage

- Iterators may only be called within `loop` statements.

- `once` mode arguments are only marked at the point of definition, not at the point of call, unlike `out` and `inout` arguments. `out` and `inout` arguments cannot be `once` arguments as well.

- Each textual instance of an iterator in a loop is distinct. The following loop prints out [2,2] [3,3] [4,4] (and not [2,3])

      loop
         a:INT := range!(2,4);
         b:INT := range!(2,4);
         #OUT + "[" + a + "," + b + "]";
      end;

- Not all iterators reach their end or quit - execution may be terminated because some other iterator in the same loop quit. See the next point.

- Iterator instances in a conditional statement are evaluated every time they are encountered. The following loop prints out [2,2] [3,2] [4,3] and then is terminated when the first iterator quits, even though the second iterator is not yet complete

      b: INT := 0;
      loop
         a:INT := range!(2,4);
         if a.is_even then
            b := range!(2,4);
         end;
         #OUT + "[" + a + "," + b + "]";
      end;

- The expressions for `self` and for `once` arguments may not themselves contain iterator calls. (Such iter calls would not be useful anyway, since they would only execute their first iteration.) Thus, the following code is illegal, even though the 'times!' iterator is a perfectly valid iterator on integers.

      loop
         a:INT := range!(3,4).times!;
      end;

- Iterators may call themselves recursively as routines do. As iterators are normally supposed to yield more than once, one should not forget to define a loop within the iterator to catch all of these results

      class BINARY_TREE is
         attr left,right:SAME; -- subtrees
         attr data:INT;
         elt!:INT is
            if void(self) then
               quit;
            end;
            yield data;
            loop
               yield left.elt!;
            end; -- yield data in the left subtree.
            loop
               yield right.elt!;
            end;
         end; -- elt!
      end; -- class BINARY_TREE

- If an iterator in complex expression quits, the surrounding expression might not be fully evaluated.

      loop
         #OUT + "(" + c.elt! + ")\n"
      end;

  When the iterator elt! terminates the surrounding loop, an opening bracket has already been printed. The expression producing the matching closing bracket will not be evaluated, hence the algorithm will always print a bogus closing bracket in the end. The standard solution looks as follows:

      loop
         #OUT + ( "(" + c.elt! + ")\n" );
      end;

  The extra paratheses force the whole line to be evaluated first. As this evaluation will be aborted by the quit of the iterator the printing evaluation will not happen for the last iterator call.

## Iterator definitions

- Iterator names always end with an exclamation mark '`!`'.

- Yield is not permitted within a protect statement (see the Chapter on Exceptions)

- Iterators enjoy the same access options as routines. Just as with routine definitions, iterator definintions may be marked private.

- Iterator overloading and conformance rules are the same as those for routines.

- An iter argument may have only one mode. Thus, it is neither possible nor meaningful to have '`once inout`' or '`once out`' arguments.

Prev | Home | Next
Loops and Iterators | Up | Iterator Examples