loopnextindex#

Purpose#

Increments an index vector to the next logical index and jumps to the specified label if the index did not wrap to the beginning.

Format#

loopnextindex lab, i, o [, dim];

Parameters:

lab:

(literal) label to jump to if loopnextindex succeeds.

i:

(Mx1 vector) indices into an array where \(M <= N\).

o:

(Nx1 vector) orders of an N-dimensional array

dim:

(scalar) \([1-M]\), index into the vector of indices i, corresponding to the dimension to walk through, positive to walk the index forward, or negative to walk backward.

Examples#

At its essence, loopnextindex provides a simple way to iterate over the orders of a multi-dimensional array.

// The orders of the array
orders = { 2, 3, 4 };

// The starting index of the array
ind = { 1, 1, 1 };

// Label to return to
lnilab:

// Print current index
print "ind = " ind;

// Loop through indices and return
// to label lnilab
loopNextIndex lnilab, ind, orders;

Running the code above, returns:

ind =
000
000
000
ind =
000
000
000
ind =
000
000
000
ind =
000
000
000
ind =
000
000
000
ind =
000
000
000
ind =
000
000
000

 ...continuing on to end with...

 ind =
000
000
000

This next example uses the variable ind to iterate over and make assignments to the array, a.

// Set orders of array
orders = { 2, 3, 4, 5, 6, 7 };

// Allocate array to zeroes
a = arrayalloc(orders, 0);

// Set starting index
ind = { 1, 1, 1, 1 };

// Label to return to
loopni:

// Set 6x7 subarray at current index
// to a random matrix
setarray a, ind, rndn(6,7);

// Loop to next index and
// return to label loopni
loopnextindex loopni, ind, orders;

This example sets each 6x7 subarray of array a, by incrementing the index at each call of loopnextindex and then going to the label loopni. When ind cannot be incremented, the program drops out of the loop and continues.

// Starting index
ind = { 1, 1, 4, 5 };

// Label
loopni2:

// Set 6x7 subarray to random matrix
setarray a, ind, rndn(6,7);

// Increment second value of index vector
// and return to label loopni2
loopnextindex loopni2, ind, orders, 2;

Using the array and vector of orders from the example above, this example increments the second value of the index vector ind during each call to loopnextindex. This loop will set the 6x7 subarrays of a that begin at \([1,1,4,5,1,1]\), \([1,2,4,5,1,1]\), and \([1,3,4,5,1,1]\), and then drop out of the loop.

Remarks#

If the argument dim is given, loopnextindex will walk through only the dimension indicated by dim in the specified direction. Otherwise, if dim is not given, each call to loopnextindex will increment i to index the next element or subarray of the corresponding array.

loopnextindex will jump to the label indicated by lab if the index can walk further in the specified dimension and direction, otherwise it will fall out of the loop and continue through the program.

When the index matches the vector of orders, the index will be reset to the beginning and program execution will resume at the statement following the loopnextindex statement.