size — Return array dimension sizes with MATLAB-compatible one-output and multi-output forms.
size(A) reports the length of each dimension of A, with scalars represented as 1x1. It follows MATLAB-compatible row-vector and multi-output size forms across supported container types.
Syntax
sz = size(A)
[d1,d2,...] = size(A)
d = size(A, dim)
sz = size(A, [dim1 dim2 ...])Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input value to inspect. |
dim | SizeArg | Yes | — | Dimension selector (scalar or vector). |
Returns
| Name | Type | Description |
|---|---|---|
sz | NumericArray | Row vector of dimension extents. |
d | IntegerScalar | Per-dimension outputs when multiple outputs are requested. |
d | IntegerScalar | Extent for selected dimension. |
Returned values from size depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
| — | More than two input arguments are provided. | size: too many input arguments |
| — | Dimension selector is not a numeric scalar/vector. | size: dimension argument must be a numeric scalar or vector |
| — | Dimension vector argument is not vector-shaped. | size: dimension vector must be a vector of positive integers |
| — | Dimension vector argument has zero elements. | size: dimension vector must contain at least one element |
| — | A dimension selector is non-finite. | size: dimension must be finite |
| — | A dimension selector is non-integer. | size: dimension must be an integer |
| — | A dimension selector is less than one. | size: dimension must be >= 1 |
| — | Output row vector tensor construction fails. | size: failed to build output |
How size works
size(A)returns a1×Nrow vector listing the extents of each dimension.size(A, dim)returns the extent of the specified dimension as a scalar. Dimensions outside the current rank return1.size(A, dims)accepts a vector of dimensions and returns the corresponding extents.- Column and row vectors are distinguished by the tensor metadata:
size(A)yields[m n]form×nmatrices,[1 n]for row vectors, and[m 1]for column vectors. - Character arrays return
[rows cols]; string scalars return[1 1]. - Cell arrays and struct scalars follow MATLAB's array semantics.
- Empty dimensions (zeros) are preserved in the output vector.
- Multiple output variables follow MATLAB rules:
[m, n, p] = size(A)peels off leading dimensions, padding with1s when the array has fewer than the requested outputs.
Does RunMat run size on the GPU?
When a value already resides on the GPU, size reads the shape metadata carried by the GPU tensor handle. No kernels are launched and no device data is gathered. If a provider does not populate the shape field on its handles, RunMat falls back to materialising the tensor on the host so the answer stays correct. The builtin never allocates device memory and always returns a host double array, making it safe to call inside fused GPU expressions without breaking residency.
Examples
Find the size of a matrix
A = [1 2 3; 4 5 6];
shape = size(A)Expected output:
shape = [2 3]Determine the number of rows in a matrix
A = randn(8, 4);
m = size(A, 1)Expected output:
m = 8Query multiple dimensions at once
A = rand(5, 4, 3);
selected = size(A, [1 3])Expected output:
selected = [5 3]Inspect a gpuArray without gathering
G = gpuArray(ones(256, 512));
shape = size(G)Expected output:
shape = [256 512]Check the size of a cell array
C = {1, 2, 3; 4, 5, 6};
grid = size(C)Expected output:
grid = [2 3]Using size with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how size changes the result.
Run a small size example, explain the result, then change one input and compare the output.
FAQ
How is size different from length?⌄
length(A) returns the length of the largest dimension, whereas size(A) returns every dimension.
What happens when I request a dimension larger than the array rank?⌄
MATLAB semantics apply: size(A, dim) returns 1 when dim exceeds the number of stored dimensions.
Can I pass a vector of dimensions?⌄
Yes. size(A, [1 3]) returns a row vector with the size of the first and third dimensions.
Does size gather GPU data?⌄
No. The runtime reads shape metadata stored alongside the GPU buffer. Gathering only happens if a provider fails to report the shape, in which case RunMat downloads the tensor before continuing.
How are row and column vectors reported?⌄
Row vectors are [1 n], column vectors are [n 1], matching MATLAB.
What about empty arrays?⌄
Empty dimensions (0-length) are preserved exactly in the returned vector.
Can I pass non-integer dimensions?⌄
No. The dimension argument must be positive integers; fractions or negatives raise an error.
How can I check multiple dimensions and keep the result on the GPU?⌄
size always returns a host double array because it is metadata. Use the values to plan GPU computations, but no GPU array is produced.
Related Array functions
Shape
cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how size is executed, line by line, in Rust.
- View the source for size in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.