What does the union function do in MATLAB / RunMat?

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 does the union function behave in MATLAB / RunMat?

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

GPU execution in RunMat

• 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 of using the union function in MATLAB / RunMat

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

How are the index outputs defined?

IA lists the positions in A that contribute to C. IB lists the positions in B for union values that do not already appear in A. Both use MATLAB's one-based indexing.

What happens if I request 'stable' ordering?

The output keeps the first occurrence order: all unique values from A appear first, followed by new values from B in the order they are encountered.

Can I use 'rows' with string or character arrays?

Yes. union accepts string arrays and character arrays with the 'rows' option, provided the inputs share the same number of columns.

How does union treat NaN values?

All NaN values are considered equal. Sorted unions place them at the end, while stable unions keep the first-seen NaN.

Does GPU execution change the behaviour?

No. When a provider does not implement a GPU kernel, RunMat automatically gathers inputs to the host, performs the union there, and returns host-resident outputs that match MATLAB semantics exactly.

What if the inputs have different shapes?

Element-wise unions accept any shapes; both inputs are flattened column-major. Row-wise unions require matching column counts and two-dimensional inputs.

Can I mix data types?

No. Inputs must belong to the same class (numeric/logical, complex, char, or string). Mixing classes produces a descriptive error.

Are scalar outputs returned as vectors?

Scalars follow MATLAB's behaviour: a 1×1 union result is represented as a scalar double.

Do trailing spaces matter for character data?

Yes. Character arrays treat every character, including trailing spaces, as significant—matching MATLAB's behaviour.

Is the 'legacy' flag supported?

No. RunMat only implements the modern MATLAB semantics. Passing 'legacy' or 'R2012a' raises an error.

See Also

unique, sort, sortrows

Source & Feedback

• Source code: crates/runmat-runtime/src/builtins/array/sorting_sets/union.rs
• Found a bug? Open an issue with details and a minimal repro.