walkindex#

Purpose#

Walks the index of an array forward or backward through a specified dimension.

Format#

new_idx = walkindex(idx, orders, dim)#

Parameters:

idx (Mx1 vector of indices into an array) – where \(M <= N\).
orders (Nx1 vector) – orders of an N-dimensional array
dim (scalar) – \([1-to-M]\), index into the vector of indices idx, specifying which dimension to walk through. A positive value will walk the index forward, while a negative value will walk backward.

Returns:

new_idx (Mx1 vector of indices) – the new index.

Examples#

Walk down the columns of a matrix#

orders = { 4, 3 };

// Starting index
idx = { 1, 1 };

// Get the next index
idx = walkindex(idx, orders, 1);

After the above code, idx will equal:

2
1

If we call it again, like this:

// Starting idx = { 2, 1 }
idx = walkindex(idx, orders, 1);

idx will be changed to:

3
1

We can see that walkindex() is incrementing the first index by one each time we call it.

Walk down the rows of a matrix#

We will continue with our example from above, but this time we will change the final input, dim, equal to two to increment the second index.

// Starting idx = { 3, 1 }
idx = walkindex(idx, orders, 2);

idx will be changed to:

3
2

Walk backwards through a 3-D array#

This example decrements the second value of the index vector idx.

orders = { 2, 4, 3 };

idx = { 2, 3, 3 };
idx = walkindex(idx, orders, -2);

      2
idx = 2
      3

Since the absolute value of the final input, dim was equal to two, the second index was modified. Since the value was negative the index was decremented.

Walk forwards through a 3-D array#

This example will continue with the final value of idx from the previous example.

// Starting idx = { 2, 2, 3 }
idx = walkindex(idx, orders, 3);

Since the final input, dim, is equal to positive three, the third element of idx is increased by one.

      2
idx = 2
      4

Remarks#

nextindex() is often more useful.
walkindex() will return a scalar error code if the index cannot walk further in the specified dimension and direction.