Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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.

example

s = struct(field,value) creates a structure array with the specified field and values. 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'},'y','c') returns s(1).x = 'a', s(2).x = 'b', s(1).y = 'c', and s(2).y = 'c'.

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

example

s = struct(field1,value1,...,fieldN,valueN) creates multiple fields. Any nonscalar cell arrays in the set value1,...,valueN must have the same dimensions.

  • 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 the nonscalar cell array. 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.

  • 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. 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. The struct function copies the properties of obj to the fields of a new scalar structure. obj cannot be an object of a fundamental data type, such as double or char. See Fundamental MATLAB Classes for the list of fundamental data types.

Examples

expand all

Create a nonscalar structure that contains a single field.

field = 'f';
value = {'some text';
         [10, 20, 30];
         magic(5)};
s = struct(field,value)
s = 3x1 struct array with fields:
    f

View the contents of each element.

s.f
ans = 
'some text'
ans = 

    10    20    30

ans = 

    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 = 1x2 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'

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

Extended Capabilities

Introduced before R2006a

Was this topic helpful?