[Swift-commit] r6313 - branches/release-0.94/docs/userguide

[hategan at ci.uchicago.edu]

Author: hategan
Date: 2013-02-23 23:21:18 -0600 (Sat, 23 Feb 2013)
New Revision: 6313

Modified:
   branches/release-0.94/docs/userguide/mappers
Log:
added clarifications about the behavioud of iterate

Modified: branches/release-0.94/docs/userguide/mappers
===================================================================
--- branches/release-0.94/docs/userguide/mappers	2013-02-23 21:09:56 UTC (rev 6312)
+++ branches/release-0.94/docs/userguide/mappers	2013-02-24 05:21:18 UTC (rev 6313)
@@ -248,8 +248,7 @@
 iterate
 ^^^^^^^
 iterate expressions allow a block of code to be evaluated repeatedly,
-with an integer parameter sweeping upwards from 0 until a termination
-condition holds.
+with an iteration variable being incremented after each iteration.
 
 The general form is:
 
@@ -259,10 +258,30 @@
 } until (terminationExpression);
 ----
 
-with the variable var starting at 0 and increasing by one in each
-iteration. That variable is in scope in the statements block and when
-evaluating the termination expression.
+Here _var_ is the iteration variable. Its initial value is 0. After each iteration,
+but before _terminationExpression_ is evaluated, the iteration variable is incremented.
+This means that if the termination expression is a function of only the iteration variable,
+the body will never be executed while the termination expression is true.
 
+Example:
+
+----
+iterate i {
+    trace(i); // will print 0, 1, and 2
+} until (i == 3);
+----
+
+Variables declared inside the body of _iterate_ can be used in the termination expression.
+However, their values will reflect the values calculated as part of the last invocation
+of the body, and may not reflect the incremented value of the iteration variable:
+
+----
+iterate i {
+    trace(i);
+    int j = i; // will print 0, 1, 2, and 3
+} until (j == 3);
+----
+
 Operators
 ~~~~~~~~~
 The following infix operators are available for use in Swift script