cat — Concatenate arrays along a specified dimension while preserving MATLAB semantics.

cat(dim, A1, A2, …) concatenates arrays along the dimension dim, producing a new array whose slices along that dimension are the input arrays. The result preserves column-major ordering and shares MATLAB's rules for implicit singleton expansion.

How cat works in RunMat

• dim is 1-based and must be a positive integer.
• All inputs must be the same class (double, logical, complex, char, string, or cell).
• 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.
• Empty inputs participate naturally—if any dimension is zero, the result is empty.
• gpuArray inputs stay on the device when an acceleration provider is registered.
• Append an optional 'like', prototype pair to request output that matches the prototype's device residency; numeric prototypes may be host tensors or gpuArray handles, while logical prototypes must remain on the CPU.

How cat runs on the GPU

When every input is a gpuArray, RunMat first calls the active provider's AccelProvider::cat hook to concatenate the buffers directly on the device. Providers that do not expose this hook trigger a transparent fallback: the operands are gathered to the host, concatenated with the same rules as CPU arrays, and uploaded back to the originating device so downstream work still sees a gpuArray. The 'like' prototype is honoured during fallback, ensuring the final residency matches your request. Mixing host arrays with gpuArray inputs is not supported—convert explicitly with gpuArray / gather to control residency.

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     8

Concatenating 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    40

Building 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   0

Joining character arrays into wider text rows

lhs = ['Run' ; 'GPU'];
rhs = ['Mat'; 'Fun'];
words = cat(2, lhs, rhs)

Expected output:

words =
    RunMat
    GPUFun

Concatenating 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)

Related functions to explore

These functions work well alongside cat. Each page has runnable examples you can try in the browser.

reshape, permute, squeeze, gpuArray, gather, circshift, diag, flip, fliplr, flipud, horzcat, ipermute, kron, repmat, rot90, tril, triu, vertcat

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cat works, line by line, in Rust.

• View cat.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing