Structure Limitations for Code Generation

You can generate C and C++ code for MATLAB® code that contains structures. Code generation supports most operations on structures, including:

  • Indexing structure fields dynamically or by using dot notation.

  • Using structures as input arguments to entry-point functions.

  • Passing structures to local functions.

  • Constructing and accessing arrays of structures.

When you generate C or C++ code for structures in MATLAB code, adhere to these restrictions.

Add Fields in the Same Order on Each Execution Path

When you create a structure, you must add fields in the same order on each execution path. For example, code generation for this function fails because it adds the fields of structure myStruct in a different order in each if statement.

function out = structPath_error(u) %#codegen
if u > 0
    myStruct.field1 = 10;
    myStruct.field2 = 20;
else
    myStruct.field2 = 30; 
    myStruct.field1 = 40;
end
out = myStruct.field1 + myStruct.field2;
end

To resolve this error, add fields to the structure in the same order on each execution path. For example:

function out = structPath_example(u) %#codegen
if u > 0
    myStruct.field1 = 10;
    myStruct.field2 = 20;
else
    myStruct.field1 = 40;
    myStruct.field2 = 30;
end
out = myStruct.field1 + myStruct.field2;
end

Do Not Modify Structure Definition After Use

You cannot add fields to a structure or change the type of a structure field after you:

  • Assign the structure or one of its fields to a variable.

  • Index into one of its fields.

  • Index into an array containing the structure.

  • Pass the structure or a structure field to a function.

For example, code generation for this function fails because the function adds a new field, field3, to the structure myStruct after the function assigns a field of the structure to a variable.

function out = structAdd_error1(u)
myStruct = struct("field1",0,"field2",0);
y = myStruct.field2;
myStruct.field3 = u*2;
out = myStruct;
end

Code generation for this function fails because the function changes the type of field1 from a double to a string after the function passes a field of the structure to the disp function.

function out = structAdd_error2(u)
myStruct = struct("field1",0,"field2",0);
disp(myStruct.field2);
myStruct.field1 = "mystring";
out = myStruct;
end

Structure Definitions Must Match Across Different Execution Paths

When your MATLAB code reassigns a structure variable outside of a conditional block, the code generator replaces the old value with the new one. Therefore, the structures do not have to have the same fields and field types. However, if the MATLAB code creates structure variables on different execution paths, the code generator must merge these definitions. Therefore, the structure variables must have the same fields and field types. For example, code generation for this function succeeds because there is only one execution path:

function out = structAssign_example(u)
myStruct = struct("field1",u,"field2",u*u);
myStruct = struct("field1","lessThan");
out = myStruct;
end

Code generation for this function fails because the function defines myStruct differently on the two execution paths:

function out = structAssign_error(u)
if u>10
    myStruct = struct("field1",u,"field2",u*u);
else
    myStruct = struct("field1","lessThan");
end
out = myStruct;
end

Dynamic Field Names Must Be Constant at Code Generation Time

You can dynamically assign field names only when the field names are constant at code generation time. For example, code generation for this function succeeds because the cell array that contains the field names is constant at code generation time.

function out = structDynamic_example %#codegen
fields = {'temperature', 'pressure', 'humidity'};
values = [25, 101.3, 60];
for i = 1:numel(fields)
    myStruct.(fields{i}) = values(i);
end
out = myStruct;
end

Code generation for this function fails because the field name is not constant at code generation time:

function out = structDynamic_error(x,y) %#codegen
myStruct = struct;
myStruct.(x) = y;
out = myStruct;
end

Structures in an Array Must Have Fields With Consistent Types

When you create an array of structures in MATLAB, the structures in the array must have the same fields, but the same field can have different data types in different members of the array. For code generation, the same field must have the same data type across all members of the array. For example, code generation for this function fails because the data type of field1 differs across the two members of array out. 

function out = structArray_error
S1 = struct("field1",1);
S2 = struct("field1",'a');
out = [S1 S2];
end

Do Not Use mxArray In Structure

You cannot assign an mxArray directly to a structure field. Convert the mxArray to a known type before assigning it to a structure field. See Working with mxArrays.

Do Not Assign Handle Classes or Sparse Arrays to Fields of Global Structure Variables

Global structure variables cannot contain handle objects or sparse arrays.

Additional Limitations for HLS Code Generation

MATLAB to HLS code generation does not support:

  • Define primary function inputs or outputs as an array of structures.

  • Use of character arrays and strings in structures.

  • Structures with cell arrays in fixed-point conversion.

  • Variable-sized structure fields.

  • Variable-sized array of structures.

  • Structures defined in external files.

See Also

| |

Topics