Using Structures :: Working with the Embedded MATLAB Subset (Embedded MATLAB™)

Embedded MATLAB™

Using Structures

On this page…
About Structures in the Embedded MATLAB Subset Elements of Structures in the Embedded MATLAB Subset Types of Structures in the Embedded MATLAB Subset Defining Local Structure Variables Defining Outputs as Structures Making Structures Persistent Indexing Substructures and Fields Assigning Values to Structures and Fields Limitations with Structures

On this page…

About Structures in the Embedded MATLAB Subset

Elements of Structures in the Embedded MATLAB Subset

Types of Structures in the Embedded MATLAB Subset

Defining Local Structure Variables

Defining Outputs as Structures

Making Structures Persistent

Indexing Substructures and Fields

Assigning Values to Structures and Fields

Limitations with Structures

About Structures in the Embedded MATLAB Subset

The Embedded MATLAB subset supports a structure data type that is based on the MATLAB structure (see Structures in the MATLAB Programming Fundamentals documentation). By imposing some restrictions, Embedded MATLAB compiles MATLAB structures to generate efficient C code with Real-Time Workshop software. In Embedded MATLAB code, you can perform a subset of the operations available for MATLAB structures, as follows:

Define structures as local or persistent variables inside Embedded MATLAB functions
Define primary function inputs as structures
Pass structures to subfunctions
Index structure fields using dot notation

Elements of Structures in the Embedded MATLAB Subset

The elements of structures are called fields. Like structures in MATLAB, the fields of a structure in the Embedded MATLAB subset can contain data of any type and size, including:

Scalars
Strings
Composite data, such as other structures
Arrays of structures

Types of Structures in the Embedded MATLAB Subset

You can define the following types of structures in Embedded MATLAB:

Type	How to Define	Details
Input	Depends on how you use Embedded MATLAB: Define structures in Embedded MATLAB Function blocks based on Simulink bus objects (requires Simulink software) Define primary function inputs based on structure definitions in the MATLAB workspace (to generate C-MEX code using Embedded MATLAB MEX, as described in Working with Embedded MATLAB MEX)	See: Using Bus Objects in the Simulink User's Guide documentation Specifying Properties of Primary Function Inputs
Output	Define structure variable in Embedded MATLAB function	See Defining Outputs as Structures.
Local	Define local structure variable in Embedded MATLAB function	See Defining Local Structure Variables.
Persistent	Declare structure variable to be persistent in Embedded MATLAB function	See Making Structures Persistent.

Defining Local Structure Variables

You can define local structures as variables inside Embedded MATLAB functions. Local structures are temporary by default, but you can make them persistent (see Making Structures Persistent).

You can define structures explicitly as scalars or arrays, as described in these topics:

Defining Scalar Structures

There are several ways to create scalar structures in Embedded MATLAB functions:

Defining Scalar Structures by Extension. You can create scalar structures by extension by adding fields to a variable using dot notation. For example, the following code creates a structure to represent a point p with coordinates x, y, and z:

...
p.x = 1;
p.y = 3;
p.z = 1;
...

You can also nest scalar structures in direct assignment statements by appending more than one field to a variable using dot notation. For example, the following code adds a color field to structure p:

...
p.color.red = .2;
p.color.green = .4;
p.color.blue = .7;
...

See Indexing Substructures and Fields.

Defining Scalar Structures Using the MATLAB struct Function. You can create scalar structures in Embedded MATLAB functions using the MATLAB struct function (see Structures in the MATLAB Programming Fundamentals documentation). When using struct in Embedded MATLAB functions, the field arguments must be scalar values. You cannot create structures of cell arrays, but you can define arrays of structures, as described in Defining Arrays of Structures.

Defining Scalar Structures by Assignment. You can define scalar structures by assigning them to preexisting structures. In the following example, p is defined as a structure that has the same properties as the predefined structure S:

...
S = struct('a',  0, 'b',  1, 'c',  2);
p = S;
...

Note You do not need to predefine the variable to which you assign the structure — in this case, p. However, if you have already defined the variable, it must have the same class, size, and complexity as the structure you assign to it.

Defining Arrays of Structures

When you create an array of structures in an Embedded MATLAB function, you must be sure that each structure field in the array has the same size, type, and complexity (see Limitations with Structures). There are several ways to create arrays of structures:

Defining an Array of Structures from a Scalar Structure. You can create an array of structures from a scalar structure by using the MATLAB repmat function, which replicates and tiles an existing scalar structure. Follow these steps:

Create a scalar structure, as described in Defining Scalar Structures.
Call repmat, passing the scalar structure and the dimensions of the array.
Assign values to each structure using standard array indexing and structure dot notation.

For example, the following code from an Embedded MATLAB function creates X, a 1-by-3 array of scalar structures. Each element of the array is defined by the structure s, which has two fields, a and b:

...
s.a = 0;
s.b = 0;
X = repmat(s,1,3);
X(1).a = 1;
X(2).a = 2;
X(3).a = 3;
X(1).b = 4;
X(2).b = 5;
X(3).b = 6;
...

Defining an Array of Structures Using Concatenation. To create a small array of structures, you can use the concatenation operator, square brackets ( [ ] ), to join one or more structures into an array (see Concatenating Matrices in the MATLAB Programming Fundamentals documentation). In Embedded MATLAB functions, all the structures that you concatenate must have the same size, class, and complexity.

For example, the following code uses concatenation and a subfunction to create the elements of a 1-by-3 structure array:

...
W = [ sab(1,2) sab(2,3) sab(4,5) ];

function s = sab(a,b)
  s.a = a;
  s.b = b;
...

Defining Outputs as Structures

You define primary function outputs as structures the same way you define local structures (see Defining Local Structure Variables). For example, the following code defines output y as a scalar structure by extension:

function y = fcn(u)
y.a = 1;
y.b = 2;
...

The next example defines output y as a structure with the same fields and values as in the previous example, but this time using the MATLAB struct function:

function y = fcn(u)
y = struct('a',1,'b',2);
...

You can also define outputs as structures by assigning them to a preexisting structure, as in this example:

function y = fcn(u)
x = struct('a',1,'b',2);
y = x;
...

See Structures in the MATLAB Programming Fundamentals documentation.

Making Structures Persistent

To make structures persist, you declare them to be persistent variables and initialize them with the isempty statement, as described in Declaring Persistent Variables.

For example, the following Embedded MATLAB function declares structure X to be persistent and initializes its fields a and b:

function f(u)
persistent X

if isempty(X)
   X.a = 1;
   X.b = 2;
end

Indexing Substructures and Fields

As in MATLAB, you index substructures and fields of structures by using dot notation. Unlike MATLAB, you must reference field values individually in Embedded MATLAB functions (see Limitations with Structures).

For example, the following code excerpt from an Embedded MATLAB function uses dot notation to index fields and substructures:

...
substruct1.a1 = 15.2;
substruct1.a2 = int8([1 2;3 4]);

mystruct = struct('ele1',20.5,'ele2',single(100),
                  'ele3',substruct1);

substruct2 = mystruct;
substruct2.ele3.a2 = 2*(substruct1.a2);
...

The following table shows how Embedded MATLAB resolves symbols in dot notation for indexing elements of the structures in this example:

Dot Notation	Symbol Resolution
`substruct1.a1`	Field `a1` of local structure `substruct1`
`substruct2.ele3.a1`	Value of field `a1` of field `ele3`, a substructure of local structure `substruct2`
`substruct2.ele3.a2(1,1)`	Value in row 1, column 1 of field `a2` of field `ele3`, a substructure of local structure `substruct2`

Assigning Values to Structures and Fields

Use these guidelines when assigning values to a structure, substructure, or field in Embedded MATLAB functions:

Operation	Conditions
Assign one structure to another structure.	You must define each structure with the same number, type, and size of fields (see Using Structures).
Assign one structure to a substructure of a different structure and vice versa.	You must define the structure with the same number, type, and size of fields as the substructure.
Assign an element of one structure to an element of another structure.	The elements must have the same type and size.

Limitations with Structures

The Embedded MATLAB subset supports MATLAB structures with the following limitations to allow efficient code generation in C:

Add Fields in Consistent Order

When you create a structure, you must add fields in the same order on each control flow path. For example, the following code generates a compiler error because it adds the fields of structure x in a different order in each if statement clause:

function y = fcn(u)
if u > 0
   x.a = 10;
   x.b = 20;
else
   x.b = 30;  % Generates an error (on variable x)
   x.a = 40;
end
y = x.a + x.b;

In this example, the assignment to x.a comes before x.b in the first if statement clause, but the assignments appear in reverse order in the else clause. Here is the corrected code:

function y = fcn(u)
if u > 0
   x.a = 10;
   x.b = 20;
else
   x.a = 40;
   x.b = 30;
end
y = x.a + x.b;

Do Not Assign mxArrays to Structures

Do Not Add New Fields After First Use of Structures

You cannot add fields to a structure after you perform any of the following operations on the structure:

Reading from the structure
Indexing into the structure array
Passing the structure to a function

For example, consider this code:

...
x.c = 10; % Declares structure and creates field c
y = x; % Reads from structure
x.d = 20; % Generates an error
...

In this example, the attempt to add a new field d after reading from structure x generates an error.

This restriction extends across the structure hierarchy. For example, you cannot add a field to a structure after operating on one of its fields or nested structures, as in this example:

function y = fcn(u)

x.c = 10;
y = x.c;
x.d = 20; % Generates an error

In this example, the attempt to add a new field d to structure x after reading from the structure's field c generates an error.

Make Structures Uniform in Arrays

Do Not Reference Fields Dynamically

Do Not Use Field Values as Constants

The Embedded MATLAB subset never considers the values stored in the fields of a structure to be constant values. Therefore, you cannot use field values to set the size or class of other data. For example, the following code generates an error:

...
Y.a = 3;
X = zeros(Y.a); % Generates an error

In this example, even though you set field a of structure Y to the value 3, Embedded MATLAB does not consider Y.a to be a constant and, therefore, it is not a valid argument to pass to the function zeros.

Reference Field Values Individually from Structure Arrays

To reference the value of a field in a structure array, you must index into the array to the structure of interest and then reference that structure's field individually using dot notation, as in this example:

...
y = X(1).a % Extracts the value of field a 
           % of the first structure in array X
...

To reference all the values of a particular field for each structure in an array, use this notation in a for loop, as in this example:

...
s.a = 0;
s.b = 0;
X = repmat(s,1,5); 
for i = 1:5   
    X(i).a = i;   
    X(i).b = i+1; 
end

This example uses the repmat function to define an array of structures, each with two fields a and b as defined by s. See Defining Local Structure Variables for more information.

Calling Functions in the Embedded MATLAB Subset

Working with Function Handles