sortrows — Sort matrix rows lexicographically with MATLAB-compatible column selection and direction controls.
sortrows reorders rows of matrices or character arrays in lexicographic order. It supports MATLAB-compatible controls for comparison columns and per-column ascending/descending direction.
Syntax
B = sortrows(A)
B = sortrows(A, column)
B = sortrows(A, direction)
B = sortrows(A, column, direction)
B = sortrows(A, ..., "ComparisonMethod", method)
B = sortrows(A, ..., "MissingPlacement", placement)All supported sortrows forms
B = sortrows(A)
B = sortrows(A, column)
B = sortrows(A, direction)
B = sortrows(A, column, direction)
B = sortrows(A, ..., "ComparisonMethod", method)
B = sortrows(A, ..., "MissingPlacement", placement)
[B, I] = sortrows(A)
[B, I] = sortrows(A, column)
[B, I] = sortrows(A, direction)
[B, I] = sortrows(A, column, direction)
[B, I] = sortrows(A, ..., "ComparisonMethod", method)
[B, I] = sortrows(A, ..., "MissingPlacement", placement)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input matrix to sort by rows. |
column | NumericArray | Yes | — | Column specification vector (negative entries request descending order). |
direction | StringScalar | Yes | "ascend" | Global row direction override: 'ascend' or 'descend'. |
arg | Any | Variadic | — | Optional column and direction arguments. |
name | StringScalar | Yes | "ComparisonMethod" | Name-value option key. |
method | StringScalar | Yes | "auto" | Comparison method: 'auto', 'real', or 'abs'. |
name | StringScalar | Yes | "MissingPlacement" | Name-value option key. |
placement | StringScalar | Yes | "auto" | NaN placement policy: 'auto', 'first', or 'last'. |
Returns
| Name | Type | Description |
|---|---|---|
B | Any | Sorted input rows. |
I | NumericArray | Permutation indices mapping sorted rows to original rows. |
Returned values from sortrows depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:sortrows:InvalidColumnIndex | Column specification indices are out of range, zero, or otherwise invalid. | sortrows: invalid column index |
RunMat:sortrows:MissingPlacementUnknown | MissingPlacement option value is unsupported. | sortrows: unsupported MissingPlacement value |
RunMat:sortrows:InvalidArgument | Option parsing receives invalid argument kinds or malformed name-value pairs. | sortrows: invalid argument |
RunMat:sortrows:ComparisonMethodUnknown | ComparisonMethod option value is unsupported. | sortrows: unsupported ComparisonMethod value |
RunMat:sortrows:UnsupportedInputType | Input cannot be converted to numeric, logical, complex, or char matrix domain. | sortrows: unsupported input type |
RunMat:sortrows:MatrixRequired | Input has rank greater than 2 where matrix input is required. | sortrows: input must be a 2-D matrix |
RunMat:sortrows:Internal | Internal conversion/allocation/provider decode fails. | sortrows: internal operation failed |
How sortrows works
sortrows(A)sorts by column1, then column2, and so on, all in ascending order.sortrows(A, C)treats the vectorCas 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 returnsI, the 1-based row permutation indices.sortrowsis 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.
Does RunMat run sortrows 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 2Sorting 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 2Sorting rows in descending order
A = [2 8; 4 1; 3 5];
B = sortrows(A, 'descend')Expected output:
B =
4 1
3 5
2 8Mixing 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 9Sorting rows of a character array
names = ['bob '; 'al '; 'ally'];
sorted = sortrows(names)Expected output:
sorted =
al
ally
bobSorting 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.0000Forcing NaN rows to the top
A = [1 NaN; NaN 2];
B = sortrows(A, 'MissingPlacement', 'first')Expected output:
B =
NaN 2
1 NaNSorting GPU-resident data with automatic host fallback
G = gpuArray([3 1; 2 4; 1 2]);
[B, I] = sortrows(G)Using sortrows with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how sortrows changes the result.
Run a small sortrows example, explain the result, then change one input and compare the output.
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.
Is there a sortrows equivalent in NumPy or pandas?⌄
— In pandas use df.sort_values(by=['col1', 'col2'], ascending=[True, False]). In NumPy there is no direct sortrows, but A[np.lexsort(A.T[::-1])] sorts rows lexicographically (NumPy's lexsort reads its keys in reverse priority, so the [::-1] restores MATLAB's left-to-right order). For descending columns, negate the corresponding key: np.lexsort([-A[:, 1], A[:, 0]]).
How do I sort by multiple columns with different directions?⌄
— Pass a signed column vector as the second argument. Positive entries sort ascending, negative entries sort descending. For example, sortrows(A, [1 -2]) sorts column 1 ascending and column 2 descending, and sortrows(A, [3 -1 2]) orders by column 3 ascending, column 1 descending, then column 2 ascending as a tiebreaker. You can also write sortrows(A, [1 2], {'ascend','descend'}) for the equivalent name-based form.
Related Array functions
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · union · unique
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how sortrows is executed, line by line, in Rust.
- View the source for sortrows in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.