RunMat
GitHub

View all functions

CategoryArray: Sorting Sets
GPUYes

What does the unique function do in MATLAB / RunMat?

unique removes duplicates from its input while providing optional index outputs that map between the original data and the returned distinct values (or rows). By default results are sorted, but you can request stable order, operate on rows, and choose whether the first or last occurrence is retained.

How does the unique function behave in MATLAB / RunMat?

  • unique(A) flattens numeric, logical, character, string, or complex arrays column-major into a vector of unique values sorted ascending.
  • [C, IA] = unique(A) also returns the indices of the selected occurrences (IA) so that C = A(IA).
  • [C, IA, IC] = unique(A) provides IC, the mapping from each element of A to the corresponding index in C.
  • unique(A, 'stable') preserves the first appearance order rather than sorting.
  • unique(A, 'rows') treats each row as an observation and returns a matrix (or char/string array) whose rows are unique.
  • unique(A, 'last') or 'first' controls which occurrence contributes to IA (defaults to 'first').
  • Combinations such as unique(A, 'rows', 'stable', 'last') follow MATLAB's precedence rules; mutually exclusive flags (e.g. 'sorted' with 'stable') are rejected.
  • Empty inputs return empty outputs with consistent dimensions.
  • Legacy switches such as 'legacy' or 'R2012a' are not supported; RunMat always follows the modern MATLAB semantics.

unique Function GPU Execution Behaviour

unique is registered as a residency sink. When the provider exposes the custom unique hook, the runtime can execute the operation entirely on the device and keep results resident. If the active provider does not implement that hook, RunMat gathers the data to host memory, performs the CPU implementation, and returns host-resident outputs so subsequent MATLAB code observes the same values and ordering.

Examples of using the unique function in MATLAB / RunMat

Getting Sorted Unique Values

A = [3 1 3 2];
C = unique(A);

Expected output:

C =
     1
     2
     3

Preserving Input Order with 'stable'

A = [4 2 4 1 2];
C = unique(A, 'stable');

Expected output:

C =
     4
     2
     1

Returning Indices for Reconstruction

A = [7 5 7 3];
[C, IA, IC] = unique(A);
reconstructed = C(IC);

Expected output:

C =
     3
     5
     7
IA =
     4
     2
     1
IC =
     3
     2
     3
     1
reconstructed =
     7
     5
     7
     3

Finding Unique Rows in a Matrix

A = [1 3; 1 3; 2 4; 1 2];
[C, IA, IC] = unique(A, 'rows');

Expected output:

C =
     1     2
     1     3
     2     4
IA =
     4
     1
     3
IC =
     2
     2
     3
     1

Selecting Last Occurrences

A = [9 8 9 7 8];
[C, IA] = unique(A, 'last');

Expected output:

C =
     7
     8
     9
IA =
     4
     5
     3

Working with Empty Arrays

A = zeros(0, 3);
[C, IA, IC] = unique(A, 'rows');

Expected output:

C =
IA =
IC =

(all outputs are empty with compatible dimensions.)

Using unique on GPU Arrays

G = gpuArray([5 3 5 1]);
[C, IA, IC] = unique(G, 'stable');

RunMat gathers G to the host (until providers implement a device kernel) and returns:

C =
     5
     3
     1
IA =
     1
     2
     4
IC =
     1
     2
     1
     3

Unique Characters in a Char Array

chars = ['m','z'; 'm','a'];
[C, IA] = unique(chars);

Expected output (C is a column vector of characters):

C =
    a
    m
    z
IA =
    4
    1
    3

Unique Strings with Row Deduplication

S = ["alpha" "beta"; "alpha" "beta"; "gamma" "beta"];
[C, IA, IC] = unique(S, 'rows', 'stable');

Expected output:

C =
  2x2 string array
    "alpha"    "beta"
    "gamma"    "beta"
IA =
     1
     3
IC =
     1
     1
     2

FAQ

Which ordering does unique use by default?

Results are sorted in ascending order unless you pass 'stable', which preserves the first occurrence order.

How are the index outputs defined?

IA indexes into the original data (or rows). IC is a column vector mapping each element (or row) of the input to the position of the corresponding unique value in C.

What do 'first' and 'last' control?

They determine whether IA references the first or last occurrence of each distinct value/row. They do not affect C or IC.

Can I combine 'rows' with 'stable' or 'last'?

Yes. All permutations of 'rows', 'stable'/'sorted', and 'first'/'last' are accepted. The runtime enforces MATLAB's validation rules.

Does unique support complex numbers or characters?

Yes. Complex values use magnitude ordering for the sorted output, and character or string arrays produce results in their native container types (char arrays and string arrays respectively).

How does unique treat NaN values?

All NaN values are considered equal. Sorted outputs place NaNs at the end; stable outputs keep their original relative order.

Are GPU arrays supported?

Yes. When a provider lacks a native kernel, RunMat gathers GPU arrays to host memory and executes the host implementation, guaranteeing MATLAB-compatible output.

Does unique preserve array shape?

Scalar outputs remain scalars. Otherwise, values are returned as column vectors (for element mode) or matrices with the same number of columns as the input (for 'rows').

What happens with empty inputs?

Empty inputs (including empty matrices) return empty outputs with matching dimensions, and index outputs are empty column vectors.

Is unique stable?

Sorting is stable where applicable; ties preserve their relative order. You can also request 'stable' explicitly.

See Also

sort, sortrows, argsort

Source & Feedback