orderfields — Reorder the top-level fields of a structure or structure array.
orderfields sorts fields or applies a reference, name list, or numeric permutation while preserving values and structure-array dimensions.
Syntax
S = orderfields(S1)
S = orderfields(S1, order)
[S, Pout] = orderfields(S1)
[S, Pout] = orderfields(S1, order)Inputs
S1- Type
Any- Required
- Yes
- Description
- Input structure.
order- Type
Any- Required
- Yes
- Description
- Reference structure, field-name collection, or numeric permutation vector.
Returns
S- Type
Any- Description
- Structure with reordered top-level fields.
Pout- Type
NumericArray- Description
- Double column vector mapping output fields to their original positions.
Returned values from orderfields depend on how many outputs the caller requests.
Errors
orderfields:TooManyInputs- When
- More than two inputs are supplied.
- Message
orderfields: expected at most two input arguments
orderfields:InvalidInput- When
- The first input is not a structure.
- Message
orderfields: first argument must be a struct or struct array
orderfields:EmptyStructArray- When
- An empty structure array is given a nonempty reference structure.
- Message
orderfields: empty struct arrays cannot adopt a non-empty reference order
Field ordering
S = orderfields(S1) sorts top-level field names in ASCII order, so uppercase letters precede lowercase letters. The returned structure contains the same field values as S1.
The second input may be a structure whose field order is used as a template, a cell or string collection containing every field name once, or a real numeric vector containing every original 1-based field position once.
Permutation output
[S,Pout] = orderfields(...) returns the original position of every field in the new order. Pout is a host double column vector and can be passed to another structure with the same field schema.
The operation applies only to top-level fields. Nested structures retain their own field order.
Structure arrays and resident values
Every structure-array element has the same field set and order. orderfields preserves the array dimensions and applies one order to every element.
Field ordering changes host metadata only. Fixed-width integers retain their exact class and payload, and nested device handles retain provider ownership without a gather or accelerator kernel.
Examples
Sort field names
s = struct('b', 1, 'B', 2, 'a', 3, 'A', 4);
t = orderfields(s)Expected output:
t has fields A, B, a, bMatch another structure
source = struct('y', 20, 'x', 10);
template = struct('x', 0, 'y', 0);
aligned = orderfields(source, template)Expected output:
aligned follows template field orderSupply field names
s = struct('a', 1, 'b', 2, 'c', 3);
t = orderfields(s, {'c', 'a', 'b'})Expected output:
t follows the requested namesSupply original positions
s = struct('first', 1, 'second', 2, 'third', 3);
t = orderfields(s, [3 1 2])Expected output:
third becomes the first fieldReuse the returned permutation
s = struct('z', 1, 'x', 2, 'y', 3);
[t, p] = orderfields(s);
u = orderfields(s, p)Expected output:
p is [2; 3; 1] and u matches tPreserve typed field values
s = struct('wide', uint64(18446744073709551615), 'small', int8(-7));
t = orderfields(s)Expected output:
the reordered values retain uint64 and int8 storageUsing orderfields with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how orderfields changes the result.
Run a small orderfields example, explain the result, then change one input and compare the output.
FAQ
How are names sorted when no order is supplied?⌄
RunMat uses ASCII ordering, with uppercase letters before lowercase letters.
What can the second input contain?⌄
A reference structure, a cell array of character vectors, a string array, or a real numeric permutation vector.
Must the field sets match?⌄
Yes. A reference or name collection must contain exactly the input fields, once each.
What does Pout contain?⌄
It is a double column vector of original 1-based field positions in the returned order.
Does orderfields reorder nested structures?⌄
No. It changes top-level field order only.
Does orderfields gather GPU values?⌄
No. Nested resident handles move with their field entries and remain owned by their provider.
Related Structs functions
Source you can read
Every RunMat function's source is public. Read exactly how orderfields is executed, line by line, in Rust.
- View the source for orderfields in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.