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.

Syntax

• `Y = circshift(A,K)` example
• `Y = circshift(A,K,dim)` example

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

collapse 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

collapse 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.