DO @Element  in  Array [Subscript]  [to Expression]  [by -1]

The Do-Array construct iterates a pointer over consecutive array elements or slices of an array. The iterator pointer may not be modified within the loop. If the pointer was previously declared it must be a Local scalar pointer with the same type as the array.

If the iterator pointer has not been declared, it will be implicitly declared with the same type as the array. If the array is an Entry parameter or a Global variable on a Use clause the implicit pointer will be declared as a Reference pointer. Otherwise it will be implicitly declared as a Wizard pointer to let you modify each element within the loop via the iterator.

If the array has only one dimension then the pointer will reference consecutive elements in the array. When the array has multiple dimensions, the pointer will access consecutive slices in the array. It iterates over the rightmost array dimension and points to the slice of the array consisting of the remaining dimensions. This is useful for scanning elements over multiple dimensions using nested loops.

 local Matrix[5, 9]  double            :Declared with [Row, Column] ordering.

DO @Row  in Matrix:                     DO over 10 Column elements giving *Row[5],
   DO @Value in Row:                       DO over 6 adjacent values in *Row[5], 
      <<< Process each element value. >>>
-  -

The value on the By clause can only be -1 and when coded scans in descending order. A Subscript can also be coded on the In clause array to designate the first element to scan. When ascending and the Subscript is omitted the iteration will start at the lower bound. When descending the scan starts at the upper bound.

The optional To clause designates the last element to scan. If both a Subscript and a To clause are coded and the Subscript index is greater than the To index then no loops will be executed.

When the To clause is out of bounds a fault exception will be raised. Also, keep in mind that array indecies are positive Word values. If the Subscript or To clause index is inadvertently negative then it is actually a large positive integer which likely exceeds the array bounds.

The pointer alway gets set when starting a loop, even when no iterations are performed. The loop may exit prematurely using the Undo command. Upon exit from the loop the pointer will reference the last array element scanned.

DO @P in Array                         :Ascend over the rightmost column.
DO @P in Array  by -1                  :Descend over the rightmost column.
DO @P in Array[ I, 2]  to 5            :Elements [I, 2] through [I, 5]
DO @P in Array[ I ]  to 0  by -1       :Elements [I] down to [0].