RunMat
GitHub

View all functions

CategoryArray: Sorting Sets
GPUYes

What does the sortrows function do in MATLAB / RunMat?

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 does the sortrows function behave in MATLAB / 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.

sortrows Function GPU Execution Behaviour

  • 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 of using sortrows in MATLAB / RunMat

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);

The runtime gathers G, performs the sort on the host, and returns host tensors. The permutation indices I match MATLAB's 1-based 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.

See Also

sort, unique, max, min, permute

Source & Feedback