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`