<!--

@license Apache-2.0

Copyright (c) 2026 The Stdlib Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->

# circshift

> Circularly shift the elements of an input [ndarray][@stdlib/ndarray/ctor] by a specified number of positions along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.

<section class="usage">

## Usage

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

#### circshift( x, k\[, options] )

Circularly shifts the elements of an input [ndarray][@stdlib/ndarray/ctor] by a specified number of positions along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.

```javascript
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][@stdlib/ndarray/ctor].
-   **k**: number of positions to shift. May be either an integer scalar value or an [ndarray][@stdlib/ndarray/ctor] having a real-valued or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] 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][@stdlib/ndarray/ctor] for `k` must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] for `k` must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
-   **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][@stdlib/ndarray/ctor].

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

```javascript
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 ] ]
```

</section>

<!-- /.usage -->

<section class="notes">

## Notes

-   The input [ndarray][@stdlib/ndarray/ctor] is shifted **in-place** (i.e., the input [ndarray][@stdlib/ndarray/ctor] 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][@stdlib/ndarray/ctor] is left unchanged.
-   The function iterates over [ndarray][@stdlib/ndarray/ctor] elements according to the memory layout of the input [ndarray][@stdlib/ndarray/ctor]. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional input [ndarray][@stdlib/ndarray/ctor]. In such scenarios, one may want to copy an input [ndarray][@stdlib/ndarray/ctor] to contiguous memory before performing the circular shift.

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var discreteUniform = require( '@stdlib/random/discrete-uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var circshift = require( '@stdlib/blas/ext/circshift' );

// Generate an ndarray of random numbers:
var x = discreteUniform( [ 5, 5 ], -20, 20, {
    'dtype': 'generic'
});
console.log( ndarray2array( x ) );

// Perform operation:
circshift( x, 2, {
    'dims': [ 0 ]
});

// Print the results:
console.log( ndarray2array( x ) );
```

</section>

<!-- /.examples -->

<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->

<section class="related">

</section>

<!-- /.related -->

<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="links">

[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor

[@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray-dtypes

[@stdlib/ndarray/base/broadcast-shapes]: https://www.npmjs.com/package/@stdlib/ndarray-base-broadcast-shapes

</section>

<!-- /.links -->
