shiftdim — Shift array dimensions, removing leading singleton axes or rotating/prepending axes explicitly.
B = shiftdim(A) removes leading singleton dimensions, retaining a two-dimensional result. [B,m] = shiftdim(A) also returns the number removed. Positive n rotates dimensions cyclically; negative n prepends singleton dimensions.
Syntax
B = shiftdim(A)
[B, m] = shiftdim(A)
B = shiftdim(A, n)Inputs
A- Type
Any- Required
- Yes
- Default
- —
- Description
- Input array or scalar.
n- Type
NumericScalar- Required
- Yes
- Default
- —
- Description
- Finite real integer dimension shift.
Returns
B- Type
Any- Description
- Array with dimensions shifted and native class preserved.
m- Type
NumericScalar- Description
- Number of leading singleton dimensions removed.
Returned values from shiftdim depend on how many outputs the caller requests.
Errors
RunMat:shiftdim:InvalidShift- When
- n is not a finite real integer scalar representable as a platform shift.
- Message
shiftdim: n must be a finite real integer scalar
RunMat:shiftdim:TooManyInputs- When
- More than two input arguments are supplied.
- Message
shiftdim: too many input arguments
RunMat:shiftdim:TooManyOutputs- When
- More than two outputs are requested, or m is requested when n is supplied.
- Message
shiftdim: invalid number of output arguments
RunMat:shiftdim:UnsupportedInput- When
- A has a type or representation that cannot express the requested shifted shape.
- Message
shiftdim: unsupported input type or shape
Forms and shape
Without n, shiftdim removes the leading singleton axes before the first non-singleton dimension. An all-singleton array remains two-dimensional and reports m = 0.
For positive n, dimensions rotate left by mod(n, ndims(A)) and column-major elements are permuted to match. For negative n, -n singleton axes are prepended without reordering element values. Explicit n has one output only.
A scalar or scalar-like host value retains its scalar representation. Dense numeric, logical, complex, character, string, cell, and structure arrays preserve their native element class. Sparse arrays support only a shift that leaves their existing two-dimensional shape unchanged.
n must be a host finite real integer scalar in the signed platform range. Native integer controls are decoded exactly; a gpuArray control, complex control, noninteger, or vector is rejected before provider work.
Execution and residency
Metadata-only numeric, logical, complex, and gpuArray shifts preserve the input payload owner; character, string, cell, and structure carriers may reconstruct their container. A positive data-reordering shift uses the input provider's permutation when available and validates the returned owner, shape, storage, and class before publication.
Paired complex integer resident data take an exact-class gathered permutation followed by restoration to the same provider. Failure to restore explicit resident data is an error, not silent host publication.
The operation is a structural fusion boundary, not an elementwise or reduction kernel. Native and browser execution reach the same runtime binding; provider work may suspend and fail after an effect.
Examples
Remove leading singleton axes and count them
A = reshape(1:6, [1 1 2 3]);
[B,m] = shiftdim(A);
size(B)
mExpected output:
ans = [2 3]
m = 2Rotate dimensions and preserve values
A = reshape(1:24, [2 3 4]);
B = shiftdim(A, 1);
size(B)Expected output:
ans = [3 4 2]Prepend singleton axes without changing data
A = reshape(1:6, [2 3]);
B = shiftdim(A, -2);
size(B)Expected output:
ans = [1 1 2 3]Using shiftdim with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how shiftdim changes the result.
Run a small shiftdim example, explain the result, then change one input and compare the output.
FAQ
When can I request the second output?⌄
Only in the form [B,m] = shiftdim(A) without an explicit shift. m counts removed leading singleton axes.
Does a negative shift move the data?⌄
No. It prepends singleton dimensions and preserves the underlying element sequence.
What happens to gpuArray input?⌄
Metadata-only shifts retain residency. Data-reordering shifts use an admitted provider permutation, or an exact-class restoration route where supported; they never silently publish an explicit resident input on the host.
Related Array functions
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · tril · triu · vertcat
Accumulation
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Creation
colon · createArray · empty · eye · false · full · inf · int16.empty · int32.empty · int64.empty · int8.empty · linspace · logspace · magic · meshgrid · nan · ndgrid · nonzeros · ones · peaks · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · uint16.empty · uint32.empty · uint64.empty · uint8.empty · zeros
Combinatorics
Binning
Grouping
Source you can read
Every RunMat function's source is public. Read exactly how shiftdim is executed, line by line, in Rust.
- View the source for shiftdim in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.