What does the length function do in MATLAB / RunMat?
length(A) returns the length of the largest dimension of A. Scalars report 1, column vectors
report their row count, row vectors return their column count, and rectangular matrices yield the
larger of their row or column dimensions. For higher-rank arrays, the function returns the maximum
extent across every dimension.
How does the length function behave in MATLAB / RunMat?
- The result is always a double-precision scalar.
- Empty arrays report
0when every dimension is zero; otherwise the maximum non-zero dimension is reported (e.g.,0×5arrays have length5). - Character arrays and string arrays follow their array dimensions, not the number of code points.
- Cell arrays use their MATLAB array shape (
rows × cols) with the maximum dimension returned. - GPU-resident arrays are inspected without gathering when the provider populates shape metadata on the tensor handle; otherwise, RunMat gathers once to recover the correct dimensions.
- Arguments that are not arrays (scalars, logicals, strings, handle objects) are treated as
1×1.
length Function GPU Execution Behaviour
length is a metadata query. When the input is a GPU tensor, RunMat looks at the shape embedded in
the GPU handle (GpuTensorHandle.shape). If the active provider leaves that metadata empty, the
runtime invokes provider.download(handle) a single time to recover the shape, ensuring
MATLAB-compatible behaviour. No GPU kernels are launched and no device buffers are allocated by this
builtin.
Examples of using the length function in MATLAB / RunMat
Determine the length of a row vector
row = [1 2 3 4];
n = length(row);
Expected output:
n = 4;
Find the longer side of a rectangular matrix
A = randn(5, 12);
len = length(A);
Expected output:
len = 12;
Handle empty arrays that still have a non-zero dimension
E = zeros(0, 7);
len = length(E);
Expected output:
len = 7;
Measure the length of a character array
name = 'RunMat';
len = length(name);
Expected output:
len = 6;
Inspect the length of a gpuArray without gathering
G = gpuArray(ones(256, 4));
len = length(G);
Expected output:
len = 256;
FAQ
How is length different from size?
length(A) returns the maximum dimension length as a scalar, whereas size(A) returns every
dimension in a row vector. Use length when you only care about the longest dimension.
What does length return for scalars?
Scalars are treated as 1×1, so length(scalar) returns 1.
How does length behave for empty arrays?
If all dimensions are zero, length returns 0. If any dimension is non-zero, the maximum
dimension is returned. For example, zeros(0, 5) has length 5, but zeros(0, 0) has length 0.
Does length gather GPU data?
No. The runtime relies on shape metadata stored in the GPU tensor handle. Only when that metadata is missing does RunMat gather the tensor to maintain correctness.
Can I use length on cell arrays and structs?
Yes. length examines the MATLAB array shape of the container, so cell arrays and struct arrays
return the maximum dimension of their array layout.
Does length count characters or bytes?
For character arrays, the length reflects the array dimensions (rows and columns), not encoded byte length or Unicode scalar counts.
What about string arrays?
String arrays are treated like any other array. String scalars are 1×1, so length("abc")
returns 1. Use strlength if you need the number of characters in each element.
Is length safe to use inside fused GPU expressions?
Yes. length never allocates or keeps data on the GPU. It returns a host scalar immediately, so it
won't break fusion plans.