walkindex
==============================================
Purpose
----------------
Walks the index of an array forward or backward through a specified dimension.
Format
----------------
.. function:: new_idx = walkindex(idx, orders, dim)
:param idx: where :math:`M <= N`.
:type idx: Mx1 vector of indices into an array
:param orders: orders of an N-dimensional array
:type orders: Nx1 vector
:param dim: :math:`[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.
:type dim: scalar
:return new_idx: the new index.
:rtype new_idx: Mx1 vector of indices
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 :func:`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
-------
* :func:`nextindex` is often more useful.
* :func:`walkindex` will return a scalar error code if the index cannot walk
further in the specified dimension and direction.
.. seealso:: Functions :func:`nextindex`, :func:`previousindex`, `loopnextindex`