union — Combine two arrays, returning their union with MATLAB-compatible ordering and index outputs.

union(A, B) creates the set-theoretic union of inputs A and B, returning a value array C that contains every distinct element (or row) appearing in either input. Optional second and third outputs provide indices back into A and B that identify which original elements contribute to each value in C.

How union works

• union(A, B) flattens the inputs column-major, removes duplicates, and returns the sorted union of their values.
• [C, IA, IB] = union(A, B) also returns index vectors where IA points to the elements in A that contribute to C and IB refers to the elements in B that only appear in B.
• union(A, B, 'stable') preserves the first-seen order: unique values from A appear first, followed by new values appearing in B.
• union(A, B, 'rows') treats each row as a record. Inputs must share the same number of columns.
• Character arrays and string arrays are fully supported in both element and row modes.
• Complex values follow MATLAB's ordering rules (magnitude first, then real/imaginary parts).
• Legacy compatibility flags ('legacy' or 'R2012a') are not supported in RunMat.

How RunMat runs union on the GPU

union is registered as a residency sink. When tensors live on a GPU and the active provider does not expose a dedicated union hook, the runtime gathers them to host memory and executes the CPU implementation to guarantee MATLAB-compatible output.

Future providers may implement ProviderHook::Custom("union") to keep data on the device.

Examples

Combining Two Numeric Vectors

A = [5 7 1];
B = [3 1 1];
[C, IA, IB] = union(A, B)

Expected output:

C =
     1
     3
     5
     7
IA =
     3
     1
     2
IB =
     1

Preserving Input Order with 'stable'

A = [5 7 1];
B = [3 2 4];
C = union(A, B, 'stable')

Expected output:

C =
     5
     7
     1
     3
     2
     4

Union of Matrix Rows

A = [1 2; 3 4; 1 2];
B = [3 4; 5 6];
[C, IA, IB] = union(A, B, 'rows')

Expected output:

C =
     1     2
     3     4
     5     6
IA =
     1
     2
IB =
     2

Working with Character Arrays

A = ['m','z'; 'm','a'];
B = ['a','x'; 'm','a'];
union(A, B)

Expected output:

ans =
  4x1 char array
    a
    m
    x
    z

Union on GPU Data

G = gpuArray([1 4 2 5]);
H = gpuArray([2 6]);
[C, IA, IB] = union(G, H)

Expected output:

C =
     1
     2
     4
     5
     6
IA =
     1
     3
     4
IB =
     2

FAQ

Related Array functions

Open-source implementation

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

• View union.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