#8 Standardise the behaviour of for loops.

docs/abi/undefined-behaviour.md

@@ -39,6 +39,9 @@ Currently, such functions may be evaluated either once or twice. This might be f
 
 * when using modifying operators: calling functions on the right-hand-side index expression than modify any of the variables used on the left hand side
 
+* when using `for` loops operators: calling non-pure functions in the range limits (like in `for i,f(),to,g()`).
+Currently, such functions may be evaluated any number of times. This might be fixed in the future.
+
 * jumping across the scope of for loop that uses a fixed list or across functions
 
 * division by zero and modulo by zero

docs/lang/syntax.md

@@ -372,7 +372,7 @@ for <variable> : [ <comma separated expressions> ]  {
 
 * `<variable>` – an already defined numeric variable
 
-* `<direction>` – the range to traverse:
+* `<direction>` – the type of range to traverse:
 
     * `to` – from `<start>` inclusive to `<end>` inclusive, in ascending order
     (e.g. `0,to,9` to traverse 0, 1,... 9)
@@ -388,6 +388,21 @@ for <variable> : [ <comma separated expressions> ]  {
     * `paralleluntil` – the same as `until`, but the iterations may be executed in any order
     
     There is no `paralleldownto`, because it would do the same as `parallelto` with swapped arguments.
+    
+    If:
+    
+    * the left argument to `until`, `paralleluntil`, `to` or `parallelto` is greater than the right argument
+    
+    * the left argument to `downto` is smaller than the right argument
+    
+    then the loop counter overflows and wraps around.
+    For example, `for i,254,to,1` with `i` being a byte, iterates over 254, 255, 0, 1.
+    
+    If the arguments to `until` or `paralleluntil` are equal, zero iterations are executed.
+    
+    `<start>` and `<end>` may be evaluated an arbitrary number of times.
+    It's recommended to use only constants, variables or other really simple expressions.
+    
 
 * `<enum type>` – traverse enum constants of given type, in arbitrary order