mat2cell — Split an array into contiguous cell-array blocks.
mat2cell partitions an array according to one size vector per selected dimension.
Syntax
C = mat2cell(A, dim1dist)
C = mat2cell(A, dim1dist, dim2dist, ...)Inputs
A- Type
Any- Required
- Yes
- Description
- Array to partition.
dimdist- Type
SizeArg- Required
- Yes
- Description
- A non-negative partition-size vector for the first dimension.
dimdist- Type
SizeArg- Required
- Variadic
- Description
- One non-negative partition-size vector per selected dimension.
Returns
C- Type
Any- Description
- Cell array containing contiguous blocks of A.
Errors
RunMat:mat2cell:TooManyOutputs- When
- More than one output is requested.
- Message
mat2cell: too many output arguments
RunMat:mat2cell:InvalidInput- When
- The input array type or argument count is invalid.
- Message
mat2cell: invalid input arguments
RunMat:mat2cell:InvalidPartition- When
- A partition vector is malformed or inconsistent with its input dimension.
- Message
mat2cell: invalid partition sizes
Partition vectors
mat2cell(A, dim1dist, dim2dist, ...) divides A into contiguous blocks. Each partition vector contains non-negative integer block sizes whose sum equals the corresponding extent of A.
Omitted trailing dimensions remain intact. Zero sizes produce empty blocks while preserving the cell grid.
Types and storage
Numeric, complex, logical, string, and character arrays are supported. Each block preserves the source class, including exact fixed-width integer storage.
In RunMat compatibility mode, partition vectors may use any fixed-width integer class. MATLAB compatibility mode accepts the documented floating numeric form.
Execution
The result is a host cell array whose shape records the number of blocks per dimension. Automatically resident inputs gather before partitioning; explicit gpuArray inputs and partition vectors are rejected until providers expose a block-splitting contract.
Each result cell owns its value-semantic block, so later mutation does not change A or another block.
Examples
Split a matrix into four blocks
A = reshape(1:16, 4, 4);
C = mat2cell(A, [2 2], [1 3]);Expected output:
C is a 2-by-2 cell arrayPartition a column vector
v = (1:6)';
C = mat2cell(v, [2 1 3]);Expected output:
The final block contains [4; 5; 6]Partition a 3-D array
A = reshape(1:24, [3 4 2]);
C = mat2cell(A, [1 2], [2 2], [1 1]);
block = C{2,1,2};Expected output:
C has shape 2-by-2-by-2Keep zero-sized blocks
A = zeros(3, 2);
C = mat2cell(A, [0 3], [1 1]);Expected output:
The first cell-grid row contains empty 0-by-1 blocksPartition character rows
names = ['foo '; 'bar '; 'baz '];
C = mat2cell(names, [1 2], size(names, 2));Expected output:
C contains one row and one two-row character blockPreserve logical blocks
A = logical([1 0 1; 0 1 0]);
C = mat2cell(A, 2, [1 1 1]);Expected output:
Each cell contains a logical columnUse exact integer partition vectors
A = uint64([1 2 3 4]);
C = mat2cell(A, uint8(1), uint16([2 2]));Expected output:
RunMat partitions exact uint64 data with typed integer controlsUsing mat2cell with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how mat2cell changes the result.
Run a small mat2cell example, explain the result, then change one input and compare the output.
FAQ
Must partition sizes sum exactly?⌄
Yes. Each supplied vector must sum to the corresponding input extent.
What happens when trailing partition vectors are omitted?⌄
Each omitted dimension remains one complete block, so its input extent is preserved within every output cell.
Are zero-sized blocks supported?⌄
Yes. A zero partition entry creates an empty block of the source class while retaining its position in the output cell grid.
Which input arrays are supported?⌄
Numeric, complex, logical, string, and character arrays are supported. Cell, structure, and object arrays are not currently supported.
Does mat2cell copy its input data?⌄
Yes. Each result cell owns a value-semantic block, so changing one block does not change the source array or another block.
Can mat2cell partition N-dimensional arrays?⌄
Yes. Supply one partition vector for each dimension that should be split; any remaining trailing dimensions stay intact.
How does mat2cell differ from num2cell?⌄
mat2cell uses explicit contiguous block sizes. num2cell creates scalar cells unless dimensions are grouped.
How can the blocks be joined again?⌄
Use cell2mat when the cell grid contains compatible array blocks whose extents form a valid rectangular layout.
Related Cells functions
Source you can read
Every RunMat function's source is public. Read exactly how mat2cell is executed, line by line, in Rust.
- View the source for mat2cell 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.