circshift circularly shifts elements or subarrays of an array (regular, of structures, cells, custom)

## Syntax

                B = circshift(A, shift)
                B = circshift(A, shift, 0)
                B = circshift(A, shifts)
                B = circshift(A, shifts, dims)

## Arguments

A, B

  row, column, matrix or 2D array, hypermatrix or ND-array of any number of dimensions and of any sizes. `B` has the shape, sizes and type of `A`. Custom types are accepted provided that `size()`, insertion, and extraction operators are defined for `A`'s type.

shift

  unique positive or negative integer: the shift to apply to indices along the first non-singleton dimension, or to linear indices of `A` components if `0` is used as third input argument.

shifts

  vector of positive or negative integers: shifts to apply on ranges along directions specified in `dims` (or `1:length(shifts)` by default).

dims

  Vector of integers in `[1, ndims(A)]`: indices of `A` dimensions along which the respective `shifts` must be performed.

## Description

`circshift(A, shift)` shifts along the first dimension of `A` of size > 1.

`circshift(A, shift, 0)` circularly shifts `A` components by `shift` positions.

`circshift(A, shifts)` circularly shifts indices of `A` rows by `shifts(1)`, indices of `A` columns by `shifts(2)`, indices of `A` layers by `shifts(3)`, etc.

`circshift(A, shifts, dims)` circularly shifts `A` by `shifts(1)` along its dimension #`dims(1)`, by `shifts(2)` along its dimension #`dims(2)`, etc.

## Examples

    circshift(1:7, 2)
    circshift(1:7, -1)

    --> circshift(1:7, 2)
     ans  =
       6.   7.   1.   2.   3.   4.   5.

    --> circshift(1:7, -1)
     ans  =
       2.   3.   4.   5.   6.   7.   1.

    M = matrix(1:12, 3, 4)
    circshift(M, 1)
    circshift(M, 1, 2)
    circshift(M, [-1 1])
    circshift(M, [-2 1], [2 1])

    --> M = matrix(1:12, 3, 4)
     M  =
       1.   4.   7.   10.
       2.   5.   8.   11.
       3.   6.   9.   12.

    --> circshift(M, 1)
     ans  =
       3.   6.   9.   12.
       1.   4.   7.   10.
       2.   5.   8.   11.

    --> circshift(M, 1, 2)
     ans  =
       10.   1.   4.   7.
       11.   2.   5.   8.
       12.   3.   6.   9.

    --> circshift(M, [-1 1])
     ans  =
       11.   2.   5.   8.
       12.   3.   6.   9.
       10.   1.   4.   7.

    --> circshift(M, [-2 1], [2 1])
     ans  =
       9.   12.   3.   6.
       7.   10.   1.   4.
       8.   11.   2.   5.

    M = matrix(1:12, 3, 4)
    circshift(M, 5, 0)

    --> circshift(M, 5, 0)
     ans  =
       8.    11.   2.   5.
       9.    12.   3.   6.
       10.   1.    4.   7.

With an hypermatrix of texts:

    t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
    circshift(t, 1, 0)
    circshift(t, 1)
    circshift(t, 1, 3)
    circshift(t, [1 -1], [2 3])

    --> t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
     t  =
    (:,:,1)
    !1  4  7  10  !
    !2  5  8  11  !
    !3  6  9  12  !

    (:,:,2)
    !a  d  g  j  !
    !b  e  h  k  !
    !c  f  i  l  !

    (:,:,3)
    !A  D  G  J  !
    !B  E  H  K  !
    !C  F  I  L  !

    --> circshift(t, 1, 0)
     ans  =
    (:,:,1)
    !L  3  6  9   !
    !1  4  7  10  !
    !2  5  8  11  !

    (:,:,2)
    !12  c  f  i  !
    !a   d  g  j  !
    !b   e  h  k  !

    (:,:,3)
    !l  C  F  I  !
    !A  D  G  J  !
    !B  E  H  K  !

    --> circshift(t, 1)
     ans  =
    (:,:,1)
    !3  6  9  12  !
    !1  4  7  10  !
    !2  5  8  11  !

    (:,:,2)
    !c  f  i  l  !
    !a  d  g  j  !
    !b  e  h  k  !

    (:,:,3)
    !C  F  I  L  !
    !A  D  G  J  !
    !B  E  H  K  !

    --> circshift(t, 1, 3)
     ans  =
    (:,:,1)
    !A  D  G  J  !
    !B  E  H  K  !
    !C  F  I  L  !

    (:,:,2)
    !1  4  7  10  !
    !2  5  8  11  !
    !3  6  9  12  !

    (:,:,3)
    !a  d  g  j  !
    !b  e  h  k  !
    !c  f  i  l  !

    --> circshift(t, [1 -1], [2 3])
     ans  =
    (:,:,1)
    !j  a  d  g  !
    !k  b  e  h  !
    !l  c  f  i  !

    (:,:,2)
    !J  A  D  G  !
    !K  B  E  H  !
    !L  C  F  I  !

    (:,:,3)
    !10  1  4  7  !
    !11  2  5  8  !
    !12  3  6  9  !

With an array of cells:

    L = list(1,%t);
    C = {%f "a" %i  %z
         %t "b" %e  %s
          0 "c" %pi L }
    circshift(C, 1, 0)
    circshift(C, 1)
    circshift(C, 1, 2)
    circshift(C, [1 -1])

## See also

- flipdim
- fftshift

## History

6.1 `circshift()` introduced.