# circshift

Shift array circularly

## Description

`Y = circshift(`

circularly
shifts the elements in array `A`

,`K`

)`A`

by `K`

positions.
If `K`

is an integer, then `circshift`

shifts
along the first dimension of `A`

whose size does
not equal 1. If `K`

is a vector of integers, then
each element of `K`

indicates the shift amount in
the corresponding dimension of `A`

.

**Note**

The default behavior of `circshift(A,K)`

where `K`

is
a scalar changed in R2016b. To preserve the behavior of R2016a and
previous releases, use `circshift(A,K,1)`

. This syntax
specifies 1 as the dimension to operate along.

## Examples

### Shift Column Vector Elements

Create a numeric column vector.

A = (1:10)'

`A = `*10×1*
1
2
3
4
5
6
7
8
9
10

Use `circshift`

to shift the elements by three positions.

Y = circshift(A,3)

`Y = `*10×1*
8
9
10
1
2
3
4
5
6
7

The result, `Y`

, has the same elements as `A`

but they are in a different order.

### Shift Characters in Array

Create an array of characters and use `circshift`

to shift the characters by 3 positions. The characters are in a different order in `Y`

.

```
A = 'racecar';
Y = circshift(A,3)
```

Y = 'carrace'

### Shift Matrix Elements

Create a numeric array with a cluster of ones in the top left.

A = [1 1 0 0; 1 1 0 0; 0 0 0 0; 0 0 0 0]

`A = `*4×4*
1 1 0 0
1 1 0 0
0 0 0 0
0 0 0 0

Use `circshift`

to shift each column of `A`

one position to the right.

Y = circshift(A,1,2)

`Y = `*4×4*
0 1 1 0
0 1 1 0
0 0 0 0
0 0 0 0

Shift the elements of `A`

by one position in each dimension. The cluster of ones is now in the center of the matrix.

Y = circshift(A,[1 1])

`Y = `*4×4*
0 0 0 0
0 1 1 0
0 1 1 0
0 0 0 0

To move the cluster back to its original position, use `circshift`

on `Y`

with negative shift values. The matrix `X`

is equivalent to `A`

.

X = circshift(Y,[-1 -1])

`X = `*4×4*
1 1 0 0
1 1 0 0
0 0 0 0
0 0 0 0

## Input Arguments

`A`

— Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `logical`

| `char`

| `string`

| `struct`

| `table`

| `cell`

**Complex Number Support: **Yes

`K`

— Shift amount

integer scalar | vector of integers

Shift amount, specified as an integer scalar or vector of integers.

If you specify

`K`

as an integer and do not specify`dim`

, then`circshift`

shifts along the first dimension whose size does not equal 1. Positive`K`

shifts toward the end of the dimension and negative`K`

shifts toward the beginning.If you specify

`K`

as a vector of integers, then the*N*th element in`K`

specifies the shift amount for the*N*th dimension in`A`

. If the*N*th element in`K`

is positive, then the values of`A`

shift toward the end of the*N*th dimension. If the*N*th element is negative, then the values shift toward the beginning.

If the shift amount is greater than the length of the corresponding
dimension in `A`

, then the shift circularly wraps
to the beginning of that dimension. For example, shifting a 3-element
vector by +3 positions brings its elements back to their original
positions.

`dim`

— Dimension to operate along

positive integer scalar

Dimension to operate along, specified as a positive integer
scalar. If no value is specified, the default is the first dimension
whose size does not equal 1. If you specify `dim`

,
then `K`

must be an integer scalar. In general, specify ```
dim
= 1
```

to exchange rows, `dim = 2`

to exchange
columns, and so on.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Code generation does not support tables and cells for the first input argument.

### GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

### Thread-Based Environment

Run code in the background using MATLAB® `backgroundPool`

or accelerate code with Parallel Computing Toolbox™ `ThreadPool`

.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

### Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

## Version History

**Introduced before R2006a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)