var circshift = require( '@stdlib/blas/ext/circshift' );

Circularly shifts the elements of an input ndarray by a specified number of positions along one or more ndarray dimensions.

var array = require( '@stdlib/ndarray/array' );

var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
// returns <ndarray>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]

var y = circshift( x, 2 );
// returns <ndarray>[ 4.0, 5.0, 1.0, 2.0, 3.0 ]

var bool = ( x === y );
// returns true

The function has the following parameters:

• x: input ndarray.
• k: number of positions to shift. May be either an integer scalar value or an ndarray having a real-valued or "generic" data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the complement of the shape defined by options.dims. For example, given the input shape [2, 3, 4] and options.dims=[0], an ndarray for k must have a shape which is broadcast-compatible with the shape [3, 4]. Similarly, when performing the operation over all elements in a provided input ndarray, an ndarray for k must be a zero-dimensional ndarray.
• options: function options (optional).

The function accepts the following options:

• dims: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input ndarray.

By default, the function circularly shifts all elements. To perform the operation over specific dimensions, provide a dims option.

var array = require( '@stdlib/ndarray/array' );

var x = array( [ 1.0, 2.0, 3.0, 4.0 ], {
    'shape': [ 2, 2 ],
    'order': 'row-major'
});
// returns <ndarray>[ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]

var y = circshift( x, 1, {
    'dims': [ 0 ]
});
// returns <ndarray>[ [ 3.0, 4.0 ], [ 1.0, 2.0 ] ]

• The input ndarray is shifted in-place (i.e., the input ndarray is mutated).
• When shifting elements along a single dimension, a positive k shifts elements to the right (toward higher indices), and a negative k shifts elements to the left (toward lower indices). If k is zero, the input ndarray is left unchanged.
• The function iterates over ndarray elements according to the memory layout of the input ndarray. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional input ndarray. In such scenarios, one may want to copy an input ndarray to contiguous memory before performing the circular shift.