Search                        Top                                  Index

HELP IN_REGION                               David Young, January 1994

The * FOR_FORM

    for ivar in_region list do ... endfor

allows iteration of a set of indices over a set of bounds in the way a
set of nested numerical for loops do.  The advantages of the
construction are that it is more compact than nested loops, and that it
does not require the programmer to know the number of indices when
writing the program. It provides a more efficient alternative to
*arrayscan.

For a closely related for form to iterate over elements of arrays, see
HELP * in_array.

The list list must contain an even number of integers. The variable ivar
is assigned a vector whose length is half that of list. The vector is
updated on each iteration to hold the current index values. The first
element of the vector varies between the first two elements of list,
inclusive, the second between the next two, and so on. All combinations
of values in the bounds are covered, with the first index varying
fastest.

For example

    for i in_region [0 1 0 1 0 1] do
        i =>
    endfor

prints

    ** {0 0 0}
    ** {1 0 0}
    ** {0 1 0}
    ** {1 1 0}
    ** {0 0 1}
    ** {1 0 1}
    ** {0 1 1}
    ** {1 1 1}

The correspondence with numerical for loops is shown, in the 2-D case,
by the following loops, which are equivalent:

    for i in_region [% x0, x1, y0, y1 %] do
        explode(i) -> (x, y);
        <   actions   >
    endfor

    {undef undef} -> i;
    for y from y0 to y1 do
        for x from x0 to x1 do
            (x, y) -> explode(i);
            <   actions   >
        endfor
    endfor

The code in the body of the loop should not assign anything to ivar, and
should not update the contents of the index vector. If it is necessary
to save the indices and continue the loop, the vector must be copied,
and not just assigned to another variable.

It is also possible to use the form

    for ivar in_region list of_dimension n do

where n gives the number of dimensions to iterate over. This must be an
integer, or a macro that expands to an integer, in the program, not an
expression or variable.  The length of list at run-time must always be
equal to 2 * n.  The main effect of including with_dimension is to make
the compiled code somewhat smaller.


--- C.all/help/in_region
--- Copyright University of Sussex 1994. All rights reserved.