coder.cstructname

Package: coder

Specify structure name in generated code

Syntax

coder.cstructname(structVar,'structName')
coder.cstructname(structVar,'structName','extern')
coder.cstructname(structVar,'structName','extern',Name,Value)
coder.cstructname(structType,'structName')
coder.cstructname(structType,'structName','extern')
coder.cstructname(structType,'structName','extern',Name,Value)

Description

coder.cstructname(structVar,'structName') allows you to specify the name of a structure in generated code. structVar is the structure variable. structName specifies the name to use for the structure variable structVar in the generated code. Use coder.cstructname(structVar, 'structName') in a function that is compiled using fiaccel. Before the first use of the structure variable in your function, you must call coder.cstructname.

coder.cstructname(structVar,'structName','extern') declares an externally defined structure. It does not generate the definition of the structure type. Provide the definition in a custom include file.

coder.cstructname(structVar,'structName','extern',Name,Value) uses additional options specified by one or more Name,Value pair arguments.

coder.cstructname(structType,'structName') returns a coder.StructType with the name structName. When the first argument is structType, coder.cstructname is a MATLAB® function. You cannot use coder.cstructname(structType, 'structName') in a function that is compiled using fiaccel. Use the returned type with the fiaccel -args option.

coder.cstructname(structType,'structName','extern') returns a coder.StructType that uses an externally defined structure. Provide the structure definition in a custom include file.

coder.cstructname(structType,'structName','extern',Name,Value) uses additional options specified by one or more Name,Value pair arguments.

Tips

  • coder.cstructname(structVar, 'structName') is ignored outside of code generation. Using coder.cstructname at the MATLAB command line, and then calling codegen does not assign a name to a structure in the generated code. For example, if function foo does not use coder.cstructname to assign a name to structure S, the following commands do not assign the name myStruct to the structure variable S in generated code.

    coder.cstructname(S,'myStruct');
    codegen foo -args {S}
  • To assign a structure name outside of code generation, use coder.cstructname(structType, 'structName'). coder.cstructname returns a coder.StructType object you can use with the -args option. For more information, see Create a coder.StructType Object.

  • To use coder.cstructname on arrays, use single indexing. For example, you cannot use coder.cstructname(x(1,2)). Instead, use single indexing, for example coder.cstructname(x(n)).

  • Use of coder.cstructname with global variables is not supported.

  • If you use coder.cstructname on an array, it sets the name of the base type of the array, not the name of the array. Therefore, you cannot use coder.cstructname on the base element and then on the array. For example, the following code does not work. The second coder.cstructname attempts to set the name of the base type to myStructArrayName, which conflicts with the previous coder.cstructname, 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,k,n); 
    coder.cstructname(myStructArray,'myStructArrayName'); 
    
    
    
  • If you are using custom structure types, specify the name of the header file that includes the external definition of the structure. Use the HeaderFile input argument.

  • If you have an Embedded Coder® license and use Code Replacement Libraries (CRLs), the CRLs provide the ability to align data objects passed into a replacement function to a specified boundary. To take advantage of target-specific function implementations that require data to be aligned, use the Alignment input argument.

  • You can also use coder.cstructname to assign a name to a substructure, which is a structure that appears as a field of another structure. For more information, see Assign a Name to a SubStructure.

Input Arguments

structName

The name to use for the structure in the generated code.

structType

coder.StructType object.

structVar

Structure variable.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'Alignment'

The run-time memory alignment of structures of this type in bytes. If you have an Embedded Coder license and use Code Replacement Libraries (CRLs), the CRLs provide the ability to align data objects passed into a replacement function to a specified boundary. This capability allows you to take advantage of target-specific function implementations that require data to be aligned. By default, the structure is not aligned on a specific boundary. Hence it is not matched by CRL functions that require alignment.

Alignment must be either -1 or a power of 2 that is not greater than 128.

Default: -1

'HeaderFile'

Name of the header file that contains the external definition of the structure, for example, "mystruct.h".

By default, the generated code contains #include statements for custom header files after the standard header files. If a standard header file refers to the custom structure type, then the compilation fails. By specifying the HeaderFile option, MATLAB Coder™ includes that header file exactly at the point where it is required.

Must be a non-empty string.

Examples

expand all

Apply coder.cstructname to Top-Level Inputs

Generate code for a MATLAB function that takes structure inputs.

  1. Write a MATLAB function, topfun, that assigns the name MyStruct to its input parameter.

    function y = topfun(x)   %#codegen
    % Assign the name 'MyStruct' to the input variable in 
    % the generated code
      coder.cstructname(x, 'MyStruct');
      y = x;
    end
  2. Declare a structure s in MATLAB. s is the structure definition for the input variable x.

    s = struct('a',42,'b',4711);
  3. Generate a MEX function for topfun, using the -args option to specify that the input parameter is a structure.

    fiaccel topfun.m -args { s }

    codegen generates a MEX function in the default folder codegen\mex\topfun. In this folder, the structure definition is in topfun_types.h.

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

Assign a Name to a SubStructure

Use coder.cstructname to assign a name to a substructure.

  1. Define a MATLAB structure, top, that has another structure, lower, as a field.

    % Define structure top with field lower, 
    % which is a structure with fields a and b
    top.lower = struct('a',1,'b',1);
    top.c = 1;
  2. Define a function, MyFunc, which takes an argument, TopVar, as input. Mark the function for code generation using %#codegen.

    function out = MyFunc(TopVar) %#codegen
  3. Inside MyFunc, include the following lines

    coder.cstructname(TopVar,'topType');
    coder.cstructname(TopVar.lower,'lowerType');
  4. Generate C code for MyFunc with an argument having the same type as top. This ensures that TopVar has the same type as top.

    codegen -config:lib MyFunc -args coder.typeof(top)

    In the generated C code, the field variable TopVar.lower is assigned the type name lowerType. For instance, the structure declaration of the variable TopVar.lower appears in the C code as:

    typedef struct
    {
        /* Definitions of a and b appear here */  
    } lowerType;

    and the structure declaration of the variable TopVar appears as:

    typedef struct
    {
         lowerType lower;
        /* Definition of c appears here */  
    } topType;

Create a coder.StructType Object

Create a coder.StructType object and pass it as argument. .

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

In this example, you create a coder.StructType object T. The object is passed as a codegen argument. However, because of the coder.cstructname statement, T is replaced with mytype in the generated C code. For instance, the declaration of T appears in the C code as:

typedef struct
{
    /* Field definitions appear here */  
} mytype;

Create a coder.StructType Object Using an Externally Defined Type

Create a C header file, MyFile.h, containing the definition of a structure type, mytype.

typedef struct {
    /* Field definitions */
    double a;
    float b;
   } mytype;

Save the file in the folder, C:\MyHeaders.

Define a coder.StructType object, T, with the same fields as mytype.

T = coder.typeof(struct('a',double(0),'b',single(0))); 

Using coder.cstructname, rename T as mytype. Specify that the definition of mytype is in MyFile.h.

T = coder.cstructname(T,'mytype','extern','HeaderFile','MyFile.h');

Generate code for MATLAB function, MyFunc, which takes a structure of type, T, as input argument. Add the folder, C:\MyHeaders, to the include path during code generation.

codegen -config:lib MyFunc -args T -I C:\MyHeaders

In the generated code, the structure, T, is assigned the name, mytype. The code generation software does not generate the definition of mytype. Instead the software includes the header file, MyFile.h, in the generated code.

More About

Was this topic helpful?