coder.cstructname

Name C structure type in generated code

collapse all in page

Syntax

coder.cstructname(var,structName)
coder.cstructname(var,structName,'extern','HeaderFile',headerfile)
coder.cstructname(var,structName,'extern','HeaderFile',headerfile,'Alignment',alignment)
outtype = coder.cstructname(intype,structName)
outtype = coder.cstructname(intype,structName,'extern','HeaderFile',headerfile)
outtype = coder.cstructname(intype,structName,'extern','HeaderFile',headerfile,'Alignment',alignment)

Description

coder.cstructname names the generated or externally defined C structure type to use for MATLAB® variables that are represented as structures in generated code.

coder.cstructname(var,structName) names the C structure type generated for the MATLAB variable var. The input var can be a structure or a cell array. Use this syntax in a function from which you generate code. Place coder.cstructname after the definition of var and before the first use of var. If var is an entry-point (top-level) function input argument, place coder.cstructname at the beginning of the function, before any control flow statements.

example

coder.cstructname(var,structName,'extern','HeaderFile',headerfile) specifies that the C structure type to use for var has the name structName and is defined in the external file, headerfileName.

It is possible to use the 'extern' option without specifying the header file. However, it is a best practice to specify the header file so that the code generator produces the #include statement in the correct location.

example

coder.cstructname(var,structName,'extern','HeaderFile',headerfile,'Alignment',alignment) also specifies the run-time memory alignment for the externally defined structure type structName. If you have Embedded Coder® and use custom Code Replacement Libraries (CRLs), specify the alignment so that the code generator can match CRL functions that require alignment for structures. See Data Alignment for Code Replacement (Embedded Coder). You cannot use this syntax if var is a cell array.

outtype = coder.cstructname(intype,structName) returns a structure or cell array type object outtype that specifies the name of the C structure type to generate. coder.cstructname creates outtype with the properties of the input type intype. Then, it sets the TypeName property to structName. Use this syntax to create a type object that you use with the codegen -args option. You cannot use this syntax in a function from which you generate code. You cannot use this syntax in a MATLAB Function block.

example

outtype = coder.cstructname(intype,structName,'extern','HeaderFile',headerfile) returns a type object outtype that specifies the name and location of an externally defined C structure type. The code generator uses the externally defined structure type for variables with type outtype. You cannot use this syntax in a MATLAB Function block.

outtype = coder.cstructname(intype,structName,'extern','HeaderFile',headerfile,'Alignment',alignment) creates a type object outtype that also specifies the C structure type alignment. You cannot use this syntax if intype is a coder.CellType object or a cell array. You cannot use this syntax in a MATLAB Function block.

Examples

collapse all

In a MATLAB function, myfun, assign the name MyStruct to the generated C structure type for the variable v.

function y = myfun()
%#codegen
v = struct('a',1,'b',2);
coder.cstructname(v, 'myStruct');
y = v;
end

Generate standalone C code. For example, generate a static library.

codegen -config:lib myfun -report

To see the generated structure type, open codegen/lib/myfun/myfun_types.h or view myfun_types.h in the code generation report. The generated C structure type is:

typedef struct {
  double a;
  double b;
} myStruct;

In a MATLAB function, myfun1, assign the name MyStruct to the generated C structure type for the structure v. Assign the name mysubStruct to the structure type generated for the substructure v.b.

function y = myfun()
%#codegen
v = struct('a',1,'b',struct('f',3));
coder.cstructname(v, 'myStruct');
coder.cstructname(v.b, 'mysubStruct');
y = v;
end

The generated C structure type mysubStruct is:

typedef struct {
  double f;
} mysubStruct;

The generated C structure type myStruct is:

typedef struct {
  double a;
  mysubStruct b;
} myStruct;

In a MATLAB function, myfun2, assign the name myStruct to the generated C structure type for the cell arrayc.

function z = myfun2()
c = {1 2 3};
coder.cstructname(c,'myStruct')
z = c;

The generated C structure type for c is:

typedef struct {
  double f1;
  double f2;
  double f3;
} myStruct;

Specify that a structure passed to a C function has a structure type defined in a C header file.

Create a C header file mycadd.h for the function mycadd that takes a parameter of type mycstruct. Define the type mycstruct in the header file.

#ifndef MYCADD_H
#define MYCADD_H

typedef struct {
    double f1;
    double f2;
} mycstruct;

double mycadd(mycstruct *s);
#endif

Write the C function mycadd.c.

#include <stdio.h>
#include <stdlib.h>

#include "mycadd.h"

double mycadd(mycstruct *s)
{
  return  s->f1 + s->f2;
}

Write a MATLAB function mymAdd that passes a structure by reference to mycadd. Use coder.cstructname to specify that in the generated code, the structure has the C type mycstruct, which is defined in mycadd.h. 

function y = mymAdd
%#codegen
s = struct('f1', 1, 'f2', 2);
coder.cstructname(s, 'mycstruct', 'extern', 'HeaderFile', 'mycadd.h');
y = 0;
y = coder.ceval('mycadd', coder.ref(s));

Generate a C static library for function mymAdd.

codegen -config:lib mymAdd mycadd.c
The generated header file mymadd_types.h does not contain a definition of the structure mycstruct because mycstruct is an external type.

Suppose that the entry-point function myFunction takes a structure argument. To specify the type of the input argument at the command line:

  1. Define an example structure S.

  2. Create a type T from S by using coder.typeof.

  3. Use coder.cstructname to create a type T1 that:

    • Has the properties of T.

    • Names the generated C structure type myStruct.

  4. Pass the type to codegen by using the -args option.

For example:

S = struct('a',double(0),'b',single(0));
T = coder.typeof(S);
T1 = coder.cstructname(T,'myStruct');
codegen -config:lib myFunction -args T1

Alternatively, you can create the structure type directly from the example structure.

S = struct('a',double(0),'b',single(0));
T1 = coder.cstructname(S,'myStruct');
codegen -config:lib myFunction -args T1

Input Arguments

collapse all

MATLAB structure or cell array variable that is represented as a structure in the generated code.

Name of generated or externally defined C structure type, specified as a character vector or string scalar.

Header file that contains the C structure type definition, specified as a character vector or string scalar.

To specify the path to the file, use one of these approaches:

  • Use the codegen command with the -I option

  • In the Code Generation Settings dialog box, set the Additional include directories (MATLAB Coder) parameter.

  • For a MATLAB Function block, on the Simulation Target and the Code Generation > Custom Code panes, under Additional build information, set the Include directories parameter.

Alternatively, use coder.updateBuildInfo with the 'addIncludePaths' option.

Example: 'mystruct.h'

Run-time memory alignment for generated or externally defined structure. Code generation does not support this argument for cell arrays or cell array types.

Structure type object, cell array type object, structure variable, or cell array variable from which to create a type object.

Limitations

  • You cannot apply coder.cstructname directly to a global variable. To name the structure type to use with a global variable, use coder.cstructname to create a type object that names the structure type. Then, when you run codegen, specify that the global variable has that type. See Name C Structure Type to Use with Global Structure Variable (MATLAB Coder).

  • For cell array inputs, the field names of externally defined structures must be f1, f2, and so on.

  • You cannot apply coder.cstructname directly to a class property.

Tips

  • For information about how the code generator determines the C/C++ types of structure fields, see Mapping MATLAB Types to Types in Generated Code (MATLAB Coder).

  • Using coder.cstructname on a structure array sets the name of the structure type of the base element, not the name of the array. Therefore, you cannot apply coder.cstructname to a structure array element, and then apply it to the array with a different C structure type name. For example, the following code is not allowed. The second coder.cstructname attempts to set the name of the base type to myStructArrayName, which conflicts with the previously specified name, myStructName.

    % Define scalar structure with field a 
myStruct = struct('a', 0); 
coder.cstructname(myStruct,'myStructName'); 
% Define array of structure with field a 
myStructArray = repmat(myStruct,4,6); 
coder.cstructname(myStructArray,'myStructArrayName');

  • Applying coder.cstructname to an element of a structure array produces the same result as applying coder.cstructname to the entire structure array. If you apply coder.cstructname to an element of a structure array, you must refer to the element by using a single subscript. For example, you can use var(1), but not var(1,1). Applying coder.cstructname to var(:) produces the same result as applying coder.cstructname to var or var(n).

  • Heterogeneous cell arrays are represented as structures in the generated code. Here are considerations for using coder.cstructname with cell arrays:

    • In a function from which you generate code, using coder.cstructname with a cell array variable makes the cell array heterogeneous. Therefore, if a cell array is an entry-point function input and its type is permanently homogeneous, then you cannot use coder.cstructname with the cell array.

    • Using coder.cstructname with a homogeneous coder.CellType object intype makes the returned object heterogeneous. Therefore, you cannot use coder.cstructname with a permanently homogeneous coder.CellType object. For information about when a cell array is permanently homogeneous, see Specify Cell Array Inputs at the Command Line (MATLAB Coder).

    • When used with a coder.CellType object, coder.cstructname creates a coder.CellType object that is permanently heterogeneous.

  • When you use a structure named by coder.cstructname in a project with row-major and column-major array layouts, the code generator renames the structure in certain cases, appending row_ or col_ to the beginning of the structure name. This renaming provides unique type definitions for the types that are used in both array layouts.

  • These tips apply only to MATLAB Function blocks:

    • MATLAB Function block input and output structures are associated with bus signals. The generated name for the structure type comes from the bus signal name. Do not use coder.cstructname to name the structure type for input or output signals. See Create Structures in MATLAB Function Blocks.

    • The code generator produces structure type names according to identifier naming rules, even if you name the structure type with coder.cstructname. If you have Embedded Coder, you can customize the naming rules. See Construction of Generated Identifiers (Embedded Coder).

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2011a

See Also

Topics