Performs
a circular shift on a rank-one array, or performs circular
shifts on all the complete rank-one sections (vectors) along a given
dimension of an array of rank two or greater.

Elements shifted off one end are inserted at the
other end. Different sections can be shifted by
different amounts and in different directions.

Class:

Transformational function; Generic

Arguments:

ARRAY

Must be an array; it can be of any data
type.

SHIFT

Must be a scalar integer or an array with
a rank that is one less than ARRAY, and shape (d1, d2, ...,
dDIM-1, dDIM+1, ..., dn), where (d1,
d2, ..., dn) is
the shape of ARRAY.

DIM (opt)

Must be a scalar integer
with a value in the range 1 to n, where n is the rank of
ARRAY. If DIM is omitted, it is assumed to be 1.

Results:

The
result is an array with the same type and kind parameters, and shape
as ARRAY.

If ARRAY has rank one, element i of the result is ARRAY (1 +
MODULO (i + SHIFT - 1, SIZE (ARRAY))). (The
same shift is applied to each element.)

If ARRAY has rank greater than one, each section (s1,s2,
..., sDIM-1, :, sDIM+1, ..., sn) of the result is shifted
as follows:

By the value of SHIFT, if SHIFT is scalar

According to the corresponding value in SHIFT(s1,
s2,..., sDIM-1, sDIM+1,..., sn),
if SHIFT is an array

The value of SHIFT determines the amount and direction of the
circular shift. A positive SHIFT value causes a shift to the left
(in rows) or up (in columns). A negative SHIFT value causes a shift
to the right (in rows) or down (in columns). A zero SHIFT value
causes no shift.

Examples

V is the array (1, 2, 3, 4, 5, 6).

CSHIFT (V, SHIFT=2) shifts the elements in V circularly to the
left by 2 positions, producing the value (3, 4, 5, 6, 1,
2). 1 and 2 are shifted off the beginning and inserted at the end.

CSHIFT (V, SHIFT= -2) shifts the elements in V circularly to the
right by 2 positions, producing the value (5, 6, 1, 2, 3,
4). 5 and 6 are shifted off the end and inserted at the beginning.

M is the array

[ 1 2 3 ]
[ 4 5 6 ]
[ 7 8 9 ].

CSHIFT (M, SHIFT = 1, DIM = 2) produces the result

[ 2 3 1 ]
[ 5 6 4 ]
[ 8 9 7 ].

Each element in rows 1, 2, and 3 is shifted to the left by
2 positions. The elements shifted off the beginning are inserted at
the end.

CSHIFT (M, SHIFT = -1, DIM = 1) produces the result

[ 7 8 9 ]
[ 1 2 3 ]
[ 4 5 6 ].

Each element in columns 1, 2, and 3 is shifted down by 1 position.
The elements shifted off the end are inserted at the beginning.

CSHIFT (M, SHIFT = (/1, -1, 0/), DIM = 2) produces the result

[ 2 3 1 ]
[ 6 4 5 ]
[ 7 8 9 ].

Each element in row 1 is shifted to the left by 1 position;
each element in row 2 is shifted to the right by 1
position; no element in row 3 is shifted at all.