RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the horzcat function do in MATLAB / RunMat?

horzcat(A1, A2, …) horizontally concatenates its inputs, matching the behaviour of MATLAB's square-bracket syntax [A1 A2 …]. It is the building block for row-wise array construction in RunMat.

How does the horzcat function behave in MATLAB / RunMat?

  • Operates on numeric, logical, complex, character, string, and cell arrays with MATLAB-compatible type checking.
  • All inputs must have the same number of rows (dimension 1). Higher dimensions are padded with singleton sizes where necessary.
  • Scalars act as 1×1 building blocks, so horzcat(1, 2, 3) produces the row vector [1 2 3].
  • Empty inputs participate naturally. If every operand is empty, the result is the canonical 0×0 double.
  • When the trailing 'like', prototype pair is supplied, the output matches the prototype's residency (host or GPU) and numeric category.
  • Mixing gpuArray operands with host operands is an error—convert explicitly using gpuArray or gather.

horzcat function GPU execution behaviour

horzcat delegates to cat(dim = 2, …). When the active acceleration provider implements the cat hook, the concatenation is executed directly on the GPU without staging data back to the CPU. Providers that lack this hook fall back to gathering the operands, concatenating on the host, and uploading the result so downstream code still sees a gpuArray. This mirrors MATLAB's explicit GPU workflow while keeping RunMat's auto-offload planner informed.

Examples of using the horzcat function in MATLAB / RunMat

Concatenating matrices by columns

A = [1 2; 3 4];
B = [10 20; 30 40];
C = horzcat(A, B);

Expected output:

C =
     1     2    10    20
     3     4    30    40

Building a row vector from scalars

row = horzcat(1, 2, 3, 4);

Expected output:

row = [1 2 3 4];

Extending character arrays into words

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

Expected output:

words =
    RunMat
    GPUFun

Keeping gpuArray inputs resident on the device

G1 = gpuArray(rand(256, 128));
G2 = gpuArray(rand(256, 64));
wide = horzcat(G1, G2);

Expected behaviour: wide remains a gpuArray with size [256 192].

Preserving empties when all inputs are empty

emptyBlock = zeros(0, 3);
result = horzcat(emptyBlock, emptyBlock);

Expected behaviour: size(result) returns [0 6] and the data stays empty.

Matching an output prototype with the 'like' syntax

proto = gpuArray.zeros(5, 1);
combo = horzcat(ones(5, 1), zeros(5, 1), "like", proto);

Expected behaviour: combo is a gpuArray of size [5 2], and stays on the GPU even if the provider falls back to the host.

FAQ

Does horzcat require at least one input?
No. Calling it with no inputs returns the canonical 0×0 double, mirroring [] in MATLAB.

Can I mix numeric, logical, and complex types?
Numeric and logical inputs can be combined; complex inputs promote real parts automatically. Mixing character, string, or cell arrays with numeric inputs is not allowed.

How do I concatenate along other dimensions?
Use cat(dim, …) for general-purpose concatenation. horzcat hard-codes dim = 2.

What happens when the row counts differ?
RunMat raises horzcat: dimension 1 mismatch …, matching MATLAB's dimension mismatch error messaging.

Can I concatenate gpuArray values with host arrays?
No. Convert all inputs to the same residency (gpuArray or host) before calling horzcat.

Does the result participate in fusion?
Concatenation is a sink operation. Fusion planners terminate the pipeline at horzcat, so subsequent operations act on the newly materialised array.

Is the output always two-dimensional?
Scalars and row vectors remain in their natural dimensionality. Higher-dimensional inputs preserve trailing dimensions from their operands.

See Also

Source & Feedback

  • Implementation: crates/runmat-runtime/src/builtins/array/shape/horzcat.rs
  • Found an issue or behavioural difference? Open a RunMat issue.