shiftdim

Shift array dimensions

Syntax

B = shiftdim(A,n)

B = shiftdim(A)

[B,m] = shiftdim(A)

Description

B = shiftdim(A,n) shifts the dimensions of an array A by n positions. shiftdim shifts the dimensions to the left when n is a positive integer and to the right when n is a negative integer. For example, if A is a 2-by-3-by-4 array, then shiftdim(A,2) returns a 4-by-2-by-3 array.

B = shiftdim(A) returns an array with the same elements as A but with leading dimensions of length 1 removed.

[B,m] = shiftdim(A) also returns the number of dimensions of length 1 that were removed.

Examples

4-D Array

Create a 4-by-2-by-3-by-5 array. Shift the dimensions 2 positions to the left, wrapping the first 2 lengths to the last 2 dimensions.

A = rand(4,2,3,5);
B = shiftdim(A,2);
size(B)

ans = 1×4

     3     5     4     2

Shift the dimensions 2 positions to the right, resulting in 2 leading dimensions of length 1. Shifting to the right does not wrap the dimension lengths.

C = shiftdim(A,-2); 
size(C)

ans = 1×6

     1     1     4     2     3     5

Shift Array Dimensions

Shift the dimensions of an array.

Compute a 5-D array A, and remove the leading dimensions of length 1. The shiftdim function shifts 2 dimensions and returns the 3-D array B.

A = rand(1,1,3,2,4);
[B,nshifts] = shiftdim(A);
nshifts

nshifts = 
2

size(B)

ans = 1×3

     3     2     4

Shift the dimensions of B twice to the left.

C = shiftdim(B,2);
size(C)

ans = 1×3

     4     3     2

Shift the dimensions of C once to the right.

D = shiftdim(C,-1); 
size(D)

ans = 1×4

     1     4     3     2

Input Arguments

A — Input array

vector | matrix | multidimensional array

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

n — Number of positions

integer

Number of dimension positions to shift, specified as an integer. When n is positive, shiftdim shifts the dimensions to the left, wrapping the leading dimensions to the end. When n is negative, shiftdim shifts the dimensions to the right, padding additional leading dimensions with length 1.

Output Arguments

B — Output array

vector | matrix | multidimensional array

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

m — Number of dimensions removed

non-negative integer

Number of dimensions removed, specified as a non-negative integer. shiftdim removes only leading dimensions of length 1.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The input array A cannot be a cell array.

• If used, the input argument n must be a constant at code generation time.

• If you do not specify the input argument n, the code generator identifies the first dimension of A that is variable size or that has a fixed size greater than 1. If this dimension is variable size at code generation time and is 1 at run time, a run-time error can occur.

• If n is positive and the last dimension of A is variable size at code generation time, this dimension cannot have a size of 1 at run time.

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

The shiftdim function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). 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