Prev Next revolve

Shift Matrix Rows in Circular Fashion
Syntax y = revolve(x, Nshift)
Include: include spt\revolve.oms
See Also shift

ARGUMENTS:
   INPUTS:  
      x      = MATRIX, any numerical type.
      Nshift = SCALAR, any numerical type, coerced to INTEGER
               before processing. Represents the number of 
               positions matrix is to be revolved.
   RETURN: MATRIX, circularly column-wise revolved version
           of input.

Description

Shift the rows of the input matrix by amount 'Nshift' in a circular fashion. Similar to a bi-directional shift-register with last stage output connected to first stage input.

For matrix inputs, each row of the matrix 'x' is shifted to higher row index for positive 'Nshift', or shifted to lower row index for negative 'Nshift'. The last row 'wraps-around' to the first row for positive 'Nshift', and in reverse direction for negative 'Nshift'. For scalar inputs or Nshift=0, function returns the input unchanged.

For the special case of a row vector being input, the function treats the vector as a column vector and revolves it accordingly, returning a row vector.

'Nshift' is internally coerced to its' integer part before revolution. Returned matrix is same type as input matrix.

Example

For Scalar Input:

O>revolve(11)
 11 

 For Row Vectors:

O>x = [1,2,3,4,5]
O>x
[   1 ,   2 ,   3 ,   4 ,   5 ] 
O>revolve(x,2)
[   4 ,   5 ,   1 ,   2 ,   3 ] 

 For Column Vectors:

O>x = {1,2,3,4,5}
O>x
{
  1
  2
  3
  4
  5
}

O>revolve(x,-2)
{
  3
  4
  5
  1
  2
}

 For Matrices:

O>x = identity(5)
O>x
{
[   1 ,   0 ,   0 ,   0 ,   0 ]
[   0 ,   1 ,   0 ,   0 ,   0 ]
[   0 ,   0 ,   1 ,   0 ,   0 ]
[   0 ,   0 ,   0 ,   1 ,   0 ]
[   0 ,   0 ,   0 ,   0 ,   1 ]
}

O>revolve(x,3)
{
[   0 ,   0 ,   1 ,   0 ,   0 ]
[   0 ,   0 ,   0 ,   1 ,   0 ]
[   0 ,   0 ,   0 ,   0 ,   1 ]
[   1 ,   0 ,   0 ,   0 ,   0 ]
[   0 ,   1 ,   0 ,   0 ,   0 ]
}