Accelerating the pace of engineering and science

# Documentation Center

• Trials
• Product Updates

# circshift

Shift array circularly

The default behavior of circshift(A,K), where K is a scalar, will change in a future release. The new default behavior will be to operate along the first array dimension of A whose size does not equal 1. Use circshift(A,[K 0]) to retain current behavior.

## Description

example

Y = circshift(A,K) circularly shifts the elements in array A by K positions. Specify K as an integer to shift the rows of A, or as a vector of integers to specify the shift amount in each dimension.

example

Y = circshift(A,K,dim) circularly shifts the values in array A by K positions along dimension dim. Inputs K and dim must be scalars.

## Examples

expand all

### Shift Column Vector Elements

Create a numeric column vector.

A = (1:10)'
A =

1
2
3
4
5
6
7
8
9
10

Use circshift to shift the elements by three positions.

Y = circshift(A,3)
Y =

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.

### Move Characters in Array

Create an array of characters.

A = 'racecar'
A =

racecar

Use circshift to shift the characters by three positions in the second dimension.

Y = circshift(A,3,2)
Y =

carrace

The characters are in a different order in Y.

### Move 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 =

1     1     0     0
1     1     0     0
0     0     0     0
0     0     0     0

Use circshift to shift the elements of A by one position in each dimension.

Y = circshift(A,[1 1])
Y =

0     0     0     0
0     1     1     0
0     1     1     0
0     0     0     0

The cluster of ones is now in the center of the matrix.

To move the cluster back to its original position, use circshift on Y with negative shift values.

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

1     1     0     0
1     1     0     0
0     0     0     0
0     0     0     0

The matrix X is equivalent to A.

## Input Arguments

expand all

### A — Input arrayvector | 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 | struct | table | cell
Complex Number Support: Yes

### K — Shift amountinteger scalar | vector of integers

Shift amount, specified as an integer scalar or vector of integers. If the shift amount is larger 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 will bring its elements back to their original positions.

• If you specify K as an integer and do not specify dim, then circshift shifts the rows of A down (positive integer) or up (negative integer).

• If you specify K as a vector of integers, each element specifies the shift amount for the Nth dimension in A. If the Nth element in K is positive, then the values of A are shifted towards the end (positive integer) or beginning (negative integer) of the Nth dimension.

### dim — Dimension to operate alongpositive integer scalar

Dimension to operate along, specified as a positive integer scalar. If no value is specified, the default is dim = 1. If you specify dim, then K must be an integer scalar. Specify dim = 1 to exchange rows, dim = 2 to exchange columns, and so on.

## See Also

Was this topic helpful?