HELP IN_REGION                                   David Young, Jan 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.


--- _____________________________________$poplocal/local/vision/help/in_region
--- _________Copyright __________University __of ______Sussex _____1994. ___All ______rights _________reserved.
