struct

Structure array

Description

A structure array is a data type that groups related data using data containers called fields. Each field can contain any type of data. Access data in a field using dot notation of the form structName.fieldName.

Creation

When you have data to put into a new structure, create the structure using dot notation to name its fields one at a time:

s.a = 1;
s.b = {'A','B','C'}

s = struct with fields:
    a: 1
    b: {'A'  'B'  'C'}

You also can create a structure array using the struct function, described below. You can specify many fields simultaneously, or create a nonscalar structure array.

Syntax

s = struct

s = struct(field,value)

s = struct(field1,value1,...,fieldN,valueN)

s = struct([])

s = struct(obj)

Description

s = struct creates a scalar (1-by-1) structure with no fields.

s = struct(field,value) creates a structure array with the specified field and value. The value input argument can be any data type, such as a numeric, logical, character, or cell array.

• If value is not a cell array, or if value is a scalar cell array, then s is a scalar structure. For instance, s = struct('a',[1 2 3]) creates a 1-by-1 structure, where s.a = [1 2 3].

• If value is a nonscalar cell array, then s is a structure array with the same dimensions as value. Each element of s contains the corresponding element of value. For example, s = struct('x',{'a','b'}) returns s(1).x = 'a' and s(2).x = 'b'.

• If value is an empty cell array {}, then s is an empty (0-by-0) structure.

s = struct(field1,value1,...,fieldN,valueN) creates a structure array with multiple fields.

• If none of the value inputs are cell arrays, or if all value inputs that are cell arrays are scalars, then s is a scalar structure.

• If any of the value inputs is a nonscalar cell array, then s has the same dimensions as that cell array. Also, if two or more value inputs are nonscalar cell arrays, then they all must have the same dimensions.

  For any value that is a scalar cell array or an array of any other data type, struct inserts the contents of value in the relevant field for all elements of s. For example, s = struct('x',{'a','b'},'y','c') returns s(1).x = 'a', s(2).x = 'b', s(1).y = 'c', and s(2).y = 'c'.

• If any value input is an empty cell array, {}, then output s is an empty (0-by-0) structure. To specify an empty field and keep the values of the other fields, use [] as a value input instead.

s = struct([]) creates an empty (0-by-0) structure with no fields.

s = struct(obj) creates a scalar structure with field names and values that correspond to properties of obj. The struct function does not convert obj, but rather creates s as a new structure. This structure does not retain the class information, so private, protected, and hidden properties become public fields in s. The struct function issues a warning when you use this syntax.

Input Arguments

field — Field name

character vector | string scalar

Field name, specified as a character vector or string scalar. Valid field names begin with a letter, and can contain letters, digits, and underscores. The maximum length of a field name is the value that the namelengthmax function returns.

value — Values

array

Values, specified as any type of array. If any value input is a nonscalar cell array, then all nonscalar cell array inputs must have the same dimensions.

If any value input is an empty cell array, {}, then the output is an empty structure array. To specify a single empty field, use [].

obj — Object

scalar | array

Object, specified as a scalar or array of objects. The struct function copies the properties of obj to the fields of a new scalar structure.

The struct function does not create a structure from most of the fundamental data types. For example, if obj has the double or char data type, then struct issues an error message. However, struct does return the properties of a table or timetable as a structure. See Fundamental MATLAB Classes for the list of fundamental data types.

Examples

Store Related Data Variables in Structure

Store related pieces of data in the fields of a structure. You can give the fields human-readable names that describe the data.

Create a structure by adding fields to it using dot notation. The fields contain x- and y-values for a sine wave, and text that describes the data.

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

Plot the sine wave. You can refer to the arrays of x- and y-values by their field names. Then add the title.

plot(data.x,data.y)
title(data.title)

Structure with One Field

Create a nonscalar structure that contains a single field.

field = 'f';
value = {'some text';
         [10, 20, 30];
         magic(5)};
s = struct(field,value)

s=3×1 struct array with fields:
    f

View the contents of each element.

s.f

ans = 
'some text'

ans = 1×3

    10    20    30

ans = 5×5

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

When you access a field of a nonscalar structure, such as s.f, MATLAB® returns a comma-separated list. In this case, s.f is equivalent to s(1).f, s(2).f, s(3).f.

Structure with Multiple Fields

Create a nonscalar structure that contains several fields.

field1 = 'f1';  value1 = zeros(1,10);
field2 = 'f2';  value2 = {'a', 'b'};
field3 = 'f3';  value3 = {pi, pi.^2};
field4 = 'f4';  value4 = {'fourth'};

s = struct(field1,value1,field2,value2,field3,value3,field4,value4)

s=1×2 struct array with fields:
    f1
    f2
    f3
    f4

The cell arrays for value2 and value3 are 1-by-2, so s is also 1-by-2. Because value1 is a numeric array and not a cell array, both s(1).f1 and s(2).f1 have the same contents. Similarly, because the cell array for value4 has a single element, s(1).f4 and s(2).f4 have the same contents.

s(1)

ans = struct with fields:
    f1: [0 0 0 0 0 0 0 0 0 0]
    f2: 'a'
    f3: 3.1416
    f4: 'fourth'

s(2)

ans = struct with fields:
    f1: [0 0 0 0 0 0 0 0 0 0]
    f2: 'b'
    f3: 9.8696
    f4: 'fourth'

Structure with Empty Field

Create a structure that contains an empty field. Use [] to specify the value of the empty field.

s = struct('f1','a','f2',[])

s = struct with fields:
    f1: 'a'
    f2: []

Fields with Cell Arrays

Create a structure with a field that contains a cell array.

field = 'mycell';
value = {{'a','b','c'}};
s = struct(field,value)

s = struct with fields:
    mycell: {'a'  'b'  'c'}

Empty Structure

Create an empty structure that contains several fields.

s = struct('a',{},'b',{},'c',{})

s = 

  0x0 empty struct array with fields:

    a
    b
    c

Assign a value to a field in an empty structure.

s(1).a = 'a'

s = struct with fields:
    a: 'a'
    b: []
    c: []

Nested Structure

Create a nested structure, where a is a structure with a field that contains another structure.

a.b = struct('c',{},'d',{})

a = struct with fields:
    b: [0x0 struct]

View the names of the fields of a.b.

fieldnames(a.b)

ans = 2x1 cell
    {'c'}
    {'d'}

Compatibility Considerations

Structure array expansion is consistent with general array expansion

Behavior changed in R2019a

Starting in R2019a, the dimensions of an expanded structure array are consistent whether you assign a value to a single field using dot notation or assign an entire structure to the array. Previously, the output dimensions were different when you did not specify indices for all dimensions. Assigning to a field using dot notation now matches the previous behavior of assigning a structure, which is consistent with general array expansion. For example:

• If S is 1-by-2-by-3-by-4, then S(5,2)=struct('a',3) and S(5,2).a=3 both expand S to 5-by-2-by-3-by-4. Previously, S(5,2).a=3 resulted in a 5-by-24 array.

• If S is 0-by-5 or 5-by-0, then S(3)=struct('a',2) and S(3).a=2 both expand S to 1-by-3. Previously, S(3).a=1 resulted in a 1-by-5 array when S was 0-by-5 and in a 3-by-1 array when S was 5-by-0.

• If S is 0-by-2-by-3, then S(3) = struct('a',2) andS(3).a=2 produce errors because it is ambiguous which dimension to expand. Previously, S(3).a=2 resulted in a 1-by-6 array.

• If S is 1-by-1-by-3 with two fields, then S(5)=struct('a',7,'b',[]) and S(5).a=7 both expand S to 1-by-1-by-5. Previously, S(5).a=7 resulted in a 1-by-5 array.

• If S is 0-by-1 with two fields, then S(5)=struct('a',7,'b',[]) and S(5).a=7 both expand S to 5-by-1. Previously, S(5).a=7 resulted in a 1-by-5 array.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• If the value argument is a cell array, all elements must have the same type.