sortrows — Sort matrix rows lexicographically with optional column and direction control.

sortrows reorders the rows of a matrix (or character array) so they appear in lexicographic order. You can control which columns participate in the comparison and whether each column uses ascending or descending order.

How sortrows works in RunMat

• sortrows(A) sorts by column 1, then column 2, and so on, all in ascending order.
• sortrows(A, C) treats the vector C as the column order. Positive entries sort ascending; negative entries sort descending.
• sortrows(A, 'descend') sorts all columns in descending order. Combine this with a column vector to mix directions.
• [B, I] = sortrows(A, ...) also returns I, the 1-based row permutation indices.
• sortrows is stable: rows that compare equal keep their original order.
• For complex inputs, 'ComparisonMethod' accepts 'auto', 'real', or 'abs', matching MATLAB semantics.
• NaN handling mirrors MATLAB: in ascending sorts rows containing NaN values move to the end; in descending sorts they move to the beginning.
• 'MissingPlacement' lets you choose whether NaN (and other missing) rows appear 'first', 'last', or follow MATLAB's 'auto' default.
• Character arrays are sorted lexicographically using their character codes.

How sortrows runs on the GPU

sortrows is registered as a sink builtin. When the input tensor already lives on the GPU and the active provider exposes a sortrows hook, the runtime delegates to that hook; the current provider contract returns host buffers, so the sorted rows and permutation indices are materialised on the CPU before being returned.

When the provider lacks the hook—or cannot honour a specific combination of options such as 'MissingPlacement','first' or 'MissingPlacement','last'—RunMat gathers the tensor and performs the sort on the host while preserving MATLAB semantics.

Name-value options that the provider does not advertize fall back automatically; callers do not need to special-case GPU vs CPU execution.

The permutation indices are emitted as double-precision column vectors so they can be reused directly for MATLAB-style indexing.

Examples

Sorting rows of a matrix in ascending order

A = [3 2; 1 4; 2 1];
B = sortrows(A)

Expected output:

B =
     1     4
     2     1
     3     2

Sorting by a custom column order

A = [1 4 2; 3 2 5; 3 2 1];
B = sortrows(A, [2 3 1])

Expected output:

B =
     3     2     1
     3     2     5
     1     4     2

Sorting rows in descending order

A = [2 8; 4 1; 3 5];
B = sortrows(A, 'descend')

Expected output:

B =
     4     1
     3     5
     2     8

Mixing ascending and descending directions

A = [1 7 3; 1 2 9; 1 2 3];
B = sortrows(A, [1 -2 3])

Expected output:

B =
     1     7     3
     1     2     3
     1     2     9

Sorting rows of a character array

names = ['bob '; 'al  '; 'ally'];
sorted = sortrows(names)

Expected output:

sorted =
al
ally
bob

Sorting rows of complex data by magnitude

Z = [3+4i, 3; 1+2i, 4];
B = sortrows(Z, 'ComparisonMethod', 'abs')

Expected output:

B =
    1.0000 + 2.0000i    4.0000
    3.0000 + 4.0000i    3.0000

Forcing NaN rows to the top

A = [1 NaN; NaN 2];
B = sortrows(A, 'MissingPlacement', 'first')

Expected output:

B =
   NaN     2
     1   NaN

Sorting GPU-resident data with automatic host fallback

G = gpuArray([3 1; 2 4; 1 2]);
[B, I] = sortrows(G)

FAQ

Can I request the permutation indices?

Yes. Call [B, I] = sortrows(A, ...) to receive the 1-based row permutation indices in I.

How do I sort specific columns?

Provide a column vector, e.g. sortrows(A, [2 -3]) sorts by column 2 ascending and column 3 descending.

What happens when rows contain NaN values?

Rows containing NaNs move to the bottom for ascending sorts and to the top for descending sorts when 'MissingPlacement' is left at its 'auto' default, matching MATLAB.

How can I force NaNs or missing values to the top or bottom?

Use the name-value pair 'MissingPlacement','first' to place missing rows before finite ones, or 'MissingPlacement','last' to move them to the end regardless of direction.

Does sortrows work with complex numbers?

Yes. Use 'ComparisonMethod','real' to sort by the real component or 'abs' to sort by magnitude (the default behaviour matches MATLAB's 'auto' rules).

Can I combine a direction string with a column vector?

Yes. sortrows(A, [1 3], 'descend') applies descending order to both columns after applying the specified column order.

Is the operation stable?

Yes. Rows that compare equal remain in their original order.

Does sortrows mutate its input?

No. It returns a sorted copy of the input. GPU inputs are gathered to host memory when required.

Are string arrays supported?

String arrays are not yet supported. Convert them to character matrices or use tables before sorting.

What does sortrows do in MATLAB?

sortrows(A) sorts the rows of matrix A in ascending order based on the elements in the first column. Rows with equal first-column values are sorted by subsequent columns.

How do I sort by a specific column in MATLAB?

Use sortrows(A, col) where col is the column index. Use negative values for descending order, e.g., sortrows(A, -2) sorts by the second column in descending order.

Is sortrows a stable sort?

Yes. sortrows uses a stable sorting algorithm, meaning rows with equal sort keys retain their original relative order.

Related functions to explore

These functions work well alongside sortrows. Each page has runnable examples you can try in the browser.

sort, unique, max, min, permute, argsort, intersect, ismember, issorted, setdiff, union

Open-source implementation

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

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