<!--
  - Authors:
  -   Denys Duchier     <duchier@ps.uni-sb.de>
  -
  - Copyright:
  -   Denys Duchier, 1999
  -
  - Last change:
  -   $Date: 1999/10/16 23:45:05 $ by $$
  -   $Revision: 1.1 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<chapter id=chapter.loop>
  <title>Loop Support</title>
  <p>A new loop facility has now been integrated into the Oz language.
It was greatly inspired by the Common Lisp loop macro.  The language
now has one additional <code/loop/ keyword.  The syntax of the loop
macro is:
<code display/loop ... end/
Within the scope of the <code/loop/ macro, a number of local macros
are allowed and described below.</p>
  <section id=section.loop.iterators>
    <title/Iterators/
    <p>A loop is typically intended to <em/iterate/ over one or more
quantities.  This is realized by iterators expressed with the
<code/for/ macro.
<list>
	<entry/<code/&lt;&lt;for X = E1 while E2 next E3&gt;&gt;//
	<item>This is very much like the C <code/for(X=E1;E2;X=E3)/
loop.  If <code/while E2/ is missing, it defaults to <code/while
true/.  If <code/next E3/ is missing, <code/X/ always keeps the same
value, &ie; it defaults to <code/next X/.</item>
	<entry/<code/&lt;&lt;for X 'from' E1 to E2 by E3&gt;&gt;//
	<item>This is very much like the C
<code/for(X=E1;X&lt;=E2;X+=E3)/ loop but introduces appropriate local
variables for <code/E2/ and <code/E3/ so that they are only computed
once.  If <code/to E2/ is missing, there is no upper limit.  If
<code/by E3/ is missing, it defaults to <code/by 1/.  If
<code/'from' E1/ is missing, it defaults to <code/'from' 1/.
<code/E3/ should always be positive.
	  <p>It is also permitted to use <code/downfrom E1/ and/or
<code/downto E2/ to indicate counting downwards.  However, <code/E3/
should still be positive.</p></item>
	<entry/<code/&lt;&lt;for X 'in' L&gt;&gt;//
	<item>Iterates over the elements of <code/L/.</item>
</list>
An iterator may be introduced anywhere within the scope of the loop
macro.  The semantics is always identical: it declares an iterator
globally for this loop.  More than one iterator may be specified: the
loop terminates as soon as one iterator terminates.  For example:
<code display>
loop
   &lt;&lt;for X 'in' [a b c d e]&gt;&gt;
   &lt;&lt;for I 'from' 1 to 3&gt;&gt;
   {Show I#X}
end
</code>
prints out:
<code display>
1#a
2#b
3#c
</code>
Note that for esthetic reasons you may like to separate the section
declaring the iterators from that of the body:
<code display>
loop
   &lt;&lt;for X 'in' [a b c d e]&gt;&gt;
   &lt;&lt;for I 'from' 1 to 3&gt;&gt;
in
   {Show I#X}
end
</code>
This is possible because the syntactic occurrence of an iterator
simply expands to <code/skip/.  Thus, in the above, the local
declarations simply contain two <code/skip/.
  </section>
  <section id=section.loop.nicer>
    <title/Nicer Syntax For Iterators/
    <p>Since the <code/for/ macro is not very pleasing for casual use,
we also support an alternative syntax for it. <code/X &lt;-- 1..N-1/
<list>
	<entry/<code/X &lt;-- L//
	<item/is short for <code/&lt;&lt;for X 'in' L&gt;&gt;//
	<entry/<code/X &lt;-- I..J//
	<item/is short for <code/&lt;&lt;for X 'from' I to J&gt;&gt;//
	<entry/<code/X &lt;-- I..J ; K//
	<item/is short for <code/&lt;&lt;for X 'from' I to J by K&gt;&gt;//
	<entry/<code/X &lt;-- E1 ; E2//
	<item/is short for <code/&lt;&lt;for X = E1 next E2&gt;&gt;//
      </list>
Thus, the common idiom:
<code display>
{List.forAllInd L
 proc {$ I X} {Show I#X} end}
</code>
can also be written:
<code display>
loop
   X &lt;-- L
   I &lt;-- 1 ; I+1
in
   {Show I#X}
end
</code></p>
  </section>
  <section id=section.loop.control>
    <title/Control/
    <p>
<list>
	<entry/<code/&lt;&lt;leave&gt;&gt;//
	<item/terminates the current loop/
        <entry/<code/&lt;&lt;next&gt;&gt;//
	<item/goes on to the next iteration of the current loop/
        <entry/<code/&lt;&lt;named L&gt;&gt;//
	<item/introduces variable L to refer to the current loop/
        <entry/<code/&lt;&lt;leave L&gt;&gt;//
	<item/terminate the loop referred to by <code/L//
        <entry/<code/&lt;&lt;next L&gt;&gt;//
	<item/goes on to the next iteration of the loop
                referred to by <code/L//
        <entry/<code/&lt;&lt;while B&gt;&gt;//
	<item/equivalent to <code/if B then skip else &lt;&lt;leave&gt;&gt; end//
        <entry/<code/&lt;&lt;until B&gt;&gt;//
	<item/equivalent to <code/if B then &lt;&lt;leave&gt;&gt; end/
      </list></p>
  </section>
  <section id=section.loop.accu>
    <title/Accumulators/
    <p>loops can also be used in expression position to accumulate
values.  The value of the implicit accumulator is returned when the
loop terminates.
<list>
	<entry/<code/&lt;&lt;collect E&gt;&gt;//
	<item/adds element E at the end of the list being
collected. Can be used together will <code/append//
        <entry/<code/&lt;&lt;append L&gt;&gt;//
	<item/appends L at the end of the list being collected.  Can
be used together with <code/collect//
        <entry/<code/&lt;&lt;count B&gt;&gt;//
	<item/if <code/B/ is true, adds 1 to the accumulated counter.
	  Can be used together with <code/sum//
        <entry/<code/&lt;&lt;sum E&gt;&gt;//
	<item/adds <code/E/ to the accumulated counter.  Can be used
together with <code/count//
        <entry/<code/&lt;&lt;maximize E&gt;&gt;//
	<item/replaces the current accumulated value if <code/E/ is greater/
        <entry/<code/&lt;&lt;minimize E&gt;&gt;//
	<item/replaces the current accumulated value if <code/E/ is smaller/
      </list></p>
  </section>
</chapter>

<!--
Local Variables:
mode: sgml
mode: auto-fill
sgml-default-dtd-file: "chapter.ced"
sgml-auto-activate-dtd: t
adaptive-fill-mode: nil
End:
-->
