coder.cstructname

Name generated or externally defined structure type in C or C++ code

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(var,structName) assigns the name structName to the C or C++ structure type generated for the MATLAB^® structure or cell array var. 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 input argument to an entry-point function, place coder.cstructname at the beginning of the function, before any control flow statements.

coder.cstructname(var,structName,"extern","HeaderFile",headerfile) assigns the name structName to the C or C++ structure type generated for the MATLAB variable var and specifies that the external file headerfile contains the definition of this C or C++ structure type.

You do not have to specify the header file when you use this syntax. However, it is a best practice to specify the header file so that the code generator produces the #include statement in the correct location.

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) generates a coder.StructType or coder.CellType object outname that mimics the structure type of intype in the generated code. The TypeName property of the created object is structName. Use this syntax to create a type object for code generation. You cannot use this syntax in a function from which you generate code. You cannot use this syntax in a MATLAB Function block.

outtype = coder.cstructname(intype,structName,"extern","HeaderFile",headerfile) generates a coder.StructType or coder.CellType object outname that mimics the structure type of intype in the generated code. The TypeName property of outtype is structName and the HeaderFile property of outtype is headerfile. Use this syntax to create a type object for code generation. When you generate code and use the outtype type object to specify an input 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) also specifies the Alignment property of the generated outtype type object. You can only use this syntax if intype is a coder.StructType object or structure. You cannot use this syntax in a MATLAB Function block.

Examples

Assign Name to Structure Type in Generated C Code

Examine the MATLAB function myStructFun, which assigns the name MyStruct to the structure type generated for the variable s in the C code.

function out = myStructFun %#codegen
s = struct("field1",1,"field2",2);
coder.cstructname(s,"myStruct");
out = s;
end

Generate standalone C code for the function myStructFun by using the codegen command. For this example, generate a static library by using the option -config:lib. Use the -launchreport option to generate and open the code generation report.

codegen -config:lib -launchreport myStructFun

Code generation successful: View report

To examine the structure type definition in the generated code, open the file myStructFun_types.h from the code generation report. The generated C code defines the myStruct structure type.

typedef struct {
  double field1;
  double field2;
} myStruct;

Assign Names to Multiple Structure Types in Generated C++ Code

Examine the MATLAB function mySubStructFun, which assigns the name myStruct to the generated structure type for the structure s and assigns the name mySubStruct to the generated substructure type generated for s.field2.

function out = mySubStructFun %#codegen
s = struct("field1",1,"field2",struct("subfield1",3));
coder.cstructname(s,"myStruct");
coder.cstructname(s.field2,"mySubStruct");
out = s;
end

Generate standalone C++ code for the function myStructFun by using the codegen command. For this example, generate a static library by using the option -config:lib and specify C++ by using the -lang:c++ option. Use the -launchreport option to generate and open the code generation report.

codegen -config:lib -lang:c++ -launchreport myStructFun

Code generation successful: View report

To examine the generated structure types, open the file mySubStructFun_types.h from the code generation report. The generated C++ code defines the mySubStruct and myStruct structure types.

struct mySubStruct {
  double subfield1;
};

struct myStruct {
  double field1;
  mySubStruct field2;
};

Assign Name to Structure Type Generated for Cell Array in C Code

When you call coder.cstructname on a cell array, the code generator transforms the cell array elements into structure fields. You can use coder.cstructname with fixed-size homogeneous and heterogeneous cell arrays. However, coder.cstructname forces homogeneous cell arrays to become heterogeneous. To learn about how the code generator defines homogenous and heterogeneous cell arrays, see Code Generation for Cell Arrays.

Examine the MATLAB function myCellFun, which defines a heterogeneous cell array, caHeterogeneous, and a homogenous cell array, caHomogenous. The function specifies the names myHomogenousCellStruct and myHeterogenousCellStruct for the structure types in the generated code. Because caHomogenous is a fixed-size homogenous array, coder.cstructname can force this cell array to be heterogeneous.

function [ca1,ca2] = myCellFun %#codegen
caHomogenous = {1 2 3};
caHeterogeneous = {[1 2] "abcdef" [4 8 10]};
coder.cstructname(caHomogenous,"myHomogenousCellStruct")
coder.cstructname(caHeterogeneous,"myHeterogenousCellStruct")
ca1 = caHomogenous;
ca2 = caHeterogeneous;
end

Generate standalone C code for the function myCellFun by using the codegen command. For this example, generate a static library by using the option -config:lib. Use the -launchreport option to generate and open the code generation report.

codegen -config:lib -launchreport myCellFun

Code generation successful: View report

To examine the generated structure type, open the file myCellFun_types.h from the code generation report. The generated C code defines the myHomogenousCellStruct and the myHeterogenousCellStruct structure type. The code generator uses generic names for the structure fields. The type definitions of the fields of each structure type match the types of the elements of the corresponding cell array.

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

typedef struct {
  char Value[6];
} rtString;

typedef struct {
  double f1[2];
  rtString f2;
  double f3[3];
} myHeterogenousCellStruct;

Use Externally Defined Structure Type in Generated C Code

Use the extern input argument to instruct the code generator to use a structure type that you define in your custom C or C++ code for a MATLAB structure or cell array.

Examine C Code

Examine the C function mycadd. The function takes an input argument of type mycstruct and sums the values in the structure fields

type mycadd.c

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

#include "mycadd.h"

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

Examine the header file mycadd.h. The header file declares the mycadd function and defines the mycstruct structure type.

type mycadd.h

#ifndef MYCADD_H
#define MYCADD_H

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

double mycadd(mycstruct *s);
#endif

Examine MATLAB Function

Examine the MATLAB function mymAdd. The function uses coder.cstructname to specify that mycstruct is an externally defined structure type that is defined in the header file mycadd.h. The function calls the C function mycadd by using coder.ceval and passes a MATLAB structure by reference by using coder.ref.

type mymAdd.m

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));
end

Generate and Examine C Code

Generate standalone C code for the function mymadd by using the codegen command. For this example, generate a static library by using the option -config:lib. Instruct the code generator to include the custom source file mycadd.c in the C code by appending the file name to the codegen command.

codegen -config:lib mymAdd mycadd.c

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.


Code generation successful (with warnings): View report

Examine the generated C function mymAdd in the file mymAdd.c. The function uses the C structure mycstruct. Because the structure is an external type, the file mymAdd_types.h does not include a definition of mycstruct.

file = fullfile("codegen","lib","mymAdd","mymAdd.c");
coder.example.extractLines(file,"double mymAdd","}",1,1)

double mymAdd(void)
{
  mycstruct s;
  s.f1 = 1.0;
  s.f2 = 2.0;
  return mycadd(&s);
}

Specify Externally Defined C/C++ Structure Type as Input Argument

Use coder.cstructname to create a coder.Type object that specifies an externally defined structure type. You can then use this object when you specify input types for code generation.

Examine C Code

Examine the C function mycmult. The function takes an input argument of type mycstruct and sums the values in the structure fields.

type mycmult.c

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

#include "mycmult.h"
#include "mycstruct.h"

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

Examine the header file mycmult.h. The header file declares the mycmult function.

type mycmult.h

#ifndef MYCMULT_H
#define MYCMULT_H

double mycmult(mycstruct *s);
#endif

Examine the header file mycstruct.h. This header file defines the mycstruct structure type. When you pass an externally defined structure as an input argument, you must add include guards in the header file to prevent the code generator from including the structure definition more than once.

type mycstruct.h

#ifndef MYCSTRUCT_H
#define MYCSTRUCT_H

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

#endif

Examine MATLAB Function

Examine the MATLAB function mymMult. The function uses coder.cstructname to specify that mycstruct is an externally defined structure type that is defined in the header file mycstruct.h. The function calls the C function mycmult by using coder.ceval and passes a MATLAB structure by reference by using coder.ref.

type mymMult.m

function y = mymMult(s) %#codegen
y = 0;
y = coder.ceval("-headerfile","mycmult.h","mycmult",coder.ref(s));
end

Create Structure Type Object

The function mymMult takes an externally defined structure as an input argument. To specify an externally defined structure type as input argument, first define a structure in MATLAB that has the same fields as the externally defined structure. Then, use coder.cstructname to generate a coder.StructType object.

For this example, define a structure, S, that has the same fields as the externally defined structure mycstruct. Then, use coder.cstructname to create a coder.StructType object from the example structure. The coder.cstructname function:

• Creates a coder.StructType object with the properties of structure S.

• Names the coder.StructType object mycstruct.

• Specifies the header file that defines mycstruct.

S = struct("f1",0,"f2",0);
T = coder.cstructname(S,"mycstruct","extern","HeaderFile","mycstruct.h")

T = 
coder.StructType
  HeaderFile: 'mycstruct.h'
  1×1 extern mycstruct struct
    f1: 1×1 double
    f2: 1×1 double

    Edit Type Object

Generate and Examine C Code

Generate standalone C code for the function mymadd by using the codegen command. For this example, generate a static library by using the option -config:lib. Pass the created structure type T to the codegen command by using the -args option. You do not need to instruct the code generator to include the custom source file mycmult.c in the codegen command because it is included by the header file mycmult.h.

codegen -config:lib mymMult -args T

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.


Code generation successful (with warnings): View report

Examine the generated C function mymMult in the file mymMult.c. The function uses the C structure mycstruct. Because the structure is an external type, the file mymMult_types.h does not include a definition of mycstruct.

file = fullfile("codegen","lib","mymMult","mymMult.c");
coder.example.extractLines(file,"double mymMult","}",1,1)

double mymMult(mycstruct *s)
{
  return mycmult(s);
}

Input Arguments

var — MATLAB value to represent as a named structure type

structure | cell array

MATLAB value to represent as a named structure type in the generated C or C++ code, specified as a structure or cell array. You can specify a structure or cell array that is itself a field of a structure or an element of a cell array.

Example: coder.cstructname(s,"myStruct");

Example: coder.cstructname(s.field2,"mySubStruct");

Example: coder.cstructname(s.field1(1).ca1{2}.ca2{x},"myNestedStruct");

structName — Name of generated or externally defined C structure type

character vector | string scalar

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

Example: coder.cstructname(s,"myStruct");

Example: coder.cstructname(s.field2,"mySubStruct");

Example: coder.cstructname(s.field1(1).ca1{2}.ca2{x},"myNestedStruct");

headerfile — Header file that contains the C structure type definition

character vector | string scalar

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

When the header file is not in the working directory, you can specify the path to the file by using one of these approaches:

• Use the codegen command with the -I option.

• In the Code Generation Settings dialog box, set the Additional include directories 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.

• In the MATLAB function, use coder.updateBuildInfo with the "addIncludePaths" option.

Example: coder.cstructname(s,"myStruct","extern","HeaderFile","myCfunc.h");

alignment — Run-time memory alignment for structure

-1 (default) | power of 2

Run-time memory alignment for generated or externally defined structure, specified as -1 or a power of 2. Code generation does not support this argument for cell arrays or coder.CellType.

Example: coder.cstructname(s,"myStruct","extern","HeaderFile","myCfunc.h","Alignment",3);

intype — MATLAB value or coder.Type object to represent as a named structure type

structure | cell array | coder.StructType | coder.CellType

MATLAB value or coder.Type object to represent as a named structure type in the generated C or C++ code, specified as a structure, cell array, coder.StructType object, or coder.CellType object.myType = coder.cstructname(s_type,"myStruct","extern","HeaderFile","myCfunc.h");

Output Arguments

outtype — coder.Type object representing var

coder.StructType object | coder.CellType object

coder.Type object representing var, returned as a coder.StructType object or a coder.CellType object. The TypeName, Alignment, and Headerfile properties of the returned object are set based on the input arguments to coder.cstructname.

Example: myType = coder.cstructname(s,"myStruct","extern","HeaderFile","myCfunc.h");

Limitations

• You cannot call coder.cstructname directly on a global variable. To name the structure type created for a global variable in the generated code, use coder.cstructname to create a type object that names the structure type. Then, when you generate code, specify that the global variable has that type. See Name C Structure Type to Use with Global Structure Variable.

• If you call coder.cstructname on a cell array and specify and externally defined type, the fields of the externally defined structure must be f1, f2, …, fn.

• You cannot call coder.cstructname directly on a class property.

• You cannot apply coder.cstructname to a homogenous cell array unless the cell array is fixed size. coder.cstructname forces the cell array to become heterogeneous, and code generation only supports fixed-size heterogeneous cell arrays. See Code Generation for Cell Arrays.

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.

• 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, code generation fails for this code snippet because the second use of coder.cstructname sets 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).

• The code generator represents heterogeneous cell arrays as structures in the generated code. When using coder.cstructname with cell arrays:

  • If a cell array is an entry-point function input and its type is permanently homogeneous, you cannot use coder.cstructname with the cell array. For information about when a cell array is permanently homogeneous, see Specify Cell Array Inputs at the Command Line.

  • You cannot use coder.cstructname with a permanently homogeneous coder.CellType object.

  • The generated coder.CellType object 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.

• 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 (Simulink).

• In a MATLAB Function block, 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

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