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

• 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 RunMat runs cat 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 Array functions

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