orderfields

Order fields of structure array

Syntax

S = orderfields(S1)

S = orderfields(S1,S2)

S = orderfields(S1,C)

S = orderfields(S1,P)

[S,Pout] = orderfields(___)

Description

S = orderfields(S1) orders the fields in S1 by name.

Since field names can contain only letters, digits, and underscores, this syntax sorts field names in ASCII order. All uppercase letters come before all lowercase letters.

S = orderfields(S1,S2) returns a copy of S1 with its fields reordered to match the order of the fields of S2. The input structure arrays S1 and S2 must have the same field names.

S = orderfields(S1,C) matches the order of the names specified in the input array C. The name of every field in S1 must appear once in C.

S = orderfields(S1,P) matches the order specified by the permutation vector P.

If S1 has n fields, then the elements of P are the integers from 1 through n, arranged in any order. For example, if S1 has three fields and P is [3 1 2], then the third field of S1 is the first field of the output S. This syntax is useful for ordering multiple structure arrays in the same way.

[S,Pout] = orderfields(___) also returns a permutation vector. The elements of Pout are the integers from 1 through n, arranged in an order that represents the change in order of the fields. You can use this syntax with any of the input arguments of the previous syntaxes.

Examples

Order Fields by Name

Create a structure with several fields.

S1 = struct('b',1,'B',2,'a',3,'A',4)

S1 = struct with fields:
    b: 1
    B: 2
    a: 3
    A: 4

Order the fields. This syntax orders the fields by their names, in ASCII order.

S = orderfields(S1)

S = struct with fields:
    A: 4
    B: 2
    a: 3
    b: 1

Order Fields Using Another Structure

Create two structures that have the same fields, in different orders. The field names are the same, but the field values are different.

S1 = struct('b',1,'B',2,'a',3,'A',4)

S1 = struct with fields:
    b: 1
    B: 2
    a: 3
    A: 4

S2 = struct('a',0,'b',20,'B',10,'A',0)

S2 = struct with fields:
    a: 0
    b: 20
    B: 10
    A: 0

Order the fields in S1 to match the order of fields in S2.

S = orderfields(S1,S2)

S = struct with fields:
    a: 3
    b: 1
    B: 2
    A: 4

List Field Names in Cell Array

Create a structure.

data.x = linspace(0,2*pi);
data.y = sin(data.x);
data.title = 'y = sin(x)'

data = struct with fields:
        x: [1x100 double]
        y: [1x100 double]
    title: 'y = sin(x)'

Order the fields by listing their names in a cell array.

C = {'title','x','y'};
data = orderfields(data,C)

data = struct with fields:
    title: 'y = sin(x)'
        x: [1x100 double]
        y: [1x100 double]

List Fields by Position Using Permutation Vector

Create a structure.

data.x = linspace(0,2*pi);
data.y = sin(data.x);
data.title = 'y = sin(x)'

data = struct with fields:
        x: [1x100 double]
        y: [1x100 double]
    title: 'y = sin(x)'

Order the fields by listing their original positions in a different order. For example, move the third field so that it is the first field of the output structure.

P = [3 1 2];
data = orderfields(data,P)

data = struct with fields:
    title: 'y = sin(x)'
        x: [1x100 double]
        y: [1x100 double]

Reorder Using Permutation Vector from Another Structure

Create a structure.

data1.x = linspace(0,2*pi);
data1.y = sin(data1.x);
data1.title = 'y = sin(x)';

Reorder the structure using the orderfields function. Store the new field order in a permutation vector Pout.

[S,Pout] = orderfields(data1,{'title','x','y'})

S = struct with fields:
    title: 'y = sin(x)'
        x: [1x100 double]
        y: [1x100 double]

Pout = 3×1

     3
     1
     2

Create a second structure with the same fields.

data2.x = data1.x;
data2.y = cos(data2.x);
data2.title = 'y = cos(x)';

Reorder the fields of data2 using Pout. If you have many structures with the same field names, then you can use Pout to reorder them all in the same way.

S2 = orderfields(data2,Pout)

S2 = struct with fields:
    title: 'y = cos(x)'
        x: [1x100 double]
        y: [1x100 double]

Input Arguments

S1 — Input structure

structure array

Input structure, specified as a structure array.

S2 — Field order by structure

structure array

Field order by structure, specified as a structure array. S2 has the same fields as S1 but specifies them in a different order.

C — Field order by name

cell array of character vectors | string array

Field order by name, specified as a cell array of character vectors or a string array. The names in C must match the field names of S1.

P — Field order by number

numeric vector

Field order by number, specified as a numeric vector. The numbers must be the integers from 1 through n, where n is the number of fields of S1.

Output Arguments

S — Reordered structure

structure array

Reordered structure, returned as a structure array. S has the same fields as S1 but they might be in a different order.

Pout — Output field order

numeric vector

Output field order, returned as a numeric vector. The elements of Pout are the integers from 1 through n, where n is the number of fields of S1. The permutation of the integers represents the change in the order of the fields.

Tips

• The orderfields function only orders top-level fields. It is not recursive.