15.5.505 roll

roll( array, target)

Returns a copy of the numerical array with its dimensions rearranged according to the value of target.

If target is an array, then (after any necessary translation to long type) it indicates the target dimension index for each dimension. Dimension number i of roll(array, target) is equal to dimension number target(i) of array, and dimen(array)(target) is equal to dimen(roll(array, target)).

target must then be a permutation of the numbers 0 through one less than the number of dimensions in array, i.e., it must have its number of elements equal to the number of dimensions of array, each element must be unique, and no element may be negative or greater than or equal to the number of dimensions of array.

For example, roll(x,[1,0,2]) is equivalent to x(>1,>0,*), and roll(x,[2,0,1]) to x(>1,>2,>0).

If target is a scalar, then (after any necessary translation to long type) it indicates over how many steps the dimension list of the result should be cyclically shifted with respect to the dimension list of array. For example, if x is a three-dimensional array, then roll(x,1) is equivalent to roll(x,[2,0,1]) and x(>1,>2,>0), and roll(x,-1) is equivalent to roll(x,[1,2,0]) and x(>2,>0,>1).