Documentation

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)

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. 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.

Tips

  • 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.

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

collapse 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.

    codegen 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 Structure and Pass it to a Function

Assign the name MyStruct to the structure structVar. Pass the structure to a C function use_struct.

  1. Create a C header file, use_struct.h, for a use_structfunction that takes a parameter of type MyStruct. Define a structure of type MyStruct in the header file.

    #ifdef MATLAB_MEX_FILE
    #include <tmwtypes.h>
    #else
    #include "rtwtypes.h"
    #endif
    
    typedef struct MyStruct
    {
        double s1;
        double s2;
    } MyStruct;
    
    void use_struct(struct MyStruct *my_struct);
    

  2. Write the C function use_struct.c.

    #include <stdio.h>
    #include <stdlib.h>
    
    #include "use_struct.h"
    
    void use_struct(struct MyStruct *my_struct)
    {
      double x = my_struct->s1;
      double y = my_struct->s2;
    }
    

  3. Write a m_use_struct compliant with MATLAB that declares a structure. Have the function assign the name MyStruct to the structure. Then, have the function call the C function use_struct using coder.ceval.

    function m_use_struct   %#codegen
    % The directive %#codegen indicates that the function
    % is intended for code generation
    % Declare a MATLAB structure
    structVar.s1 = 1;
    structVar.s2 = 2;
    
    % Assign the name MyStruct to the structure variable.
    % extern indicates this is an externally defined 
    % structure.
    coder.cstructname(structVar, 'MyStruct', 'extern');
    
    % Call the C function use_struct. The type of structVar 
    % matches the signature of use_struct.
    % Use coder.rref to pass the the variable structVar by 
    % reference as a read-only input to the external C 
    % function use_struct
    coder.ceval('use_struct', coder.rref(structVar));
    

  4. Generate C library code for function m_use_struct, passing use_struct.h to include the structure definition.

    codegen -config:lib m_use_struct use_struct.c use_struct.h
    codegen generates C code in the default folder codegen\lib\m_use_struct. The generated header file m_use_struct_types.h in this folder does not contain a definition of the structure MyStruct because MyStruct is an external type.

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;
Was this topic helpful?