cat — Concatenate arrays along a chosen dimension in MATLAB and RunMat.
cat(dim, A1, A2, ...) concatenates arrays along dimension dim, producing a new array whose slices along that dimension come from the inputs. Non-concatenated dimensions must be size-compatible, and ordering follows MATLAB and RunMat column-major semantics.
Syntax
B = cat(dim, A1, A2, An...)
B = cat(dim, A1, A2, An..., "like", prototype)Inputs
dim- Type
NumericScalar- Required
- Yes
- Description
- Concatenation dimension (1-based).
A1- Type
Any- Required
- Yes
- Description
- First input array.
A2- Type
Any- Required
- Yes
- Description
- Second input array.
An- Type
Any- Required
- Variadic
- Description
- Additional input arrays.
name- Type
PropertyName- Required
- Yes
- Default
"like"- Description
- Name-value key ('like').
prototype- Type
LikePrototype- Required
- Yes
- Description
- Prototype that sets output class/device.
Returns
B- Type
Any- Description
- Concatenated output array.
Errors
RunMat:cat:TooFewInputs- When
- Fewer than two input arrays are supplied after dim.
- Message
cat: at least two input arrays are required
RunMat:cat:InvalidDimension- When
- dim is non-numeric, non-integer, or less than one.
- Message
cat: dimension must be numeric and >= 1
RunMat:cat:GpuError- When
- A required gpuArray gather, upload, or provider operation fails.
- Message
cat: gpuArray operation failed
Behavior
dim is 1-based and must be a positive integer.
Valid unlike-class combinations follow concatenation precedence: string dominates real numeric, character, and logical data; character dominates real numeric data but cannot combine with logical; an integer operand makes the leftmost nonempty integer class dominate real floating and logical operands; otherwise single dominates double, and logical is preserved only when every input is logical.
Every ordered mixture of the eight real integer classes is accepted. When a nonempty input remains, empty operands are omitted before class selection; otherwise the leftmost integer class determines output class. Other numeric or logical values convert with ordinary rounding and saturation.
Dimensions other than dim must match exactly; missing higher dimensions are treated as size 1 automatically.
The size along dim becomes the sum of the corresponding sizes from each input.
An empty operand is omitted when a nonempty compatible partner remains; compatible all-empty inputs retain the concatenated empty geometry.
gpuArray inputs stay on the device when an acceleration provider is registered, and real or complex numeric host inputs may be mixed with resident inputs in the same call. Paired complex-integer data retains its exact component class and owning provider.
RunMat compatibility mode adds an optional trailing "like", prototype pair that can request host or GPU output residency; this pair is not part of the pinned public MATLAB syntax.
Execution and residency
Runs on the GPU when the provider offers a native cat hook; typed integer data, mixed host/device calls, runtime empty omission, or providers without the hook use exact gather, host assembly, and upload fallback.
This structural operation is a fusion boundary, not an elementwise or reduction kernel.
Examples
Concatenating matrices by stacking rows
A = [1 2; 3 4];
B = [5 6; 7 8];
C = cat(1, A, B)Expected output:
C =
1 2
3 4
5 6
7 8Concatenating matrices by appending columns
left = [1 3; 2 4];
right = [10 30; 20 40];
wide = cat(2, left, right)Expected output:
wide =
1 3 10 30
2 4 20 40Building a 3-D array from 2-D slices
slice1 = magic(3);
slice2 = eye(3);
cube = cat(3, slice1, slice2)Concatenating logical masks without type changes
row = logical([1 0 1]);
mask = cat(1, row, ~row)Expected output:
mask =
1 0 1
0 1 0Joining character arrays into wider text rows
lhs = ['Run' ; 'GPU'];
rhs = ['Mat'; 'Fun'];
words = cat(2, lhs, rhs)Expected output:
words =
RunMat
GPUFunConcatenating string arrays along rows
names = ["alpha" "beta"];
more = ["gamma" "delta"];
combined = cat(1, names, more)Appending cell array columns for table-like data
cols1 = {1, 2; 'a', 'b'};
cols2 = {3, 4; 'c', 'd'};
tableCells = cat(2, cols1, cols2)Keeping gpuArray inputs on the device
G1 = gpuArray(rand(256, 256));
G2 = gpuArray(rand(256, 256));
stacked = cat(3, G1, G2)Requesting GPU output with the "like" prototype
G = gpuArray(rand(3, 3));
H = cat(3, zeros(3, 3), ones(3, 3), "like", G)Concatenating complex arrays preserves imaginary parts
z1 = complex([1 2], [3 4]);
z2 = complex([5 6], [7 8]);
joined = cat(2, z1, z2)Combining empty inputs yields an empty result
emptyRow = zeros(0, 3);
combo = cat(1, emptyRow, emptyRow)Using cat with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how cat changes the result.
Run a small cat example, explain the result, then change one input and compare the output.
Related Array functions
Shape
blkdiag · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · shiftdim · 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 cat is executed, line by line, in Rust.
- View the source for cat 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.