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.

Description

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

example

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.

example

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

expand all

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.

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 [].

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

collapse all

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)

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
    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.

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=2×4 struct
    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'

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: []

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

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: []

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 array
    {'c'}
    {'d'}

Compatibility Considerations

expand all

Behavior changed in R2019a

Extended Capabilities

Introduced before R2006a