Documentation

coder.cstructname

Package: coder

Name structure in generated code

Syntax

coder.cstructname(var,'structName')
coder.cstructname(var,'structName','extern')
coder.cstructname(var,'structName','extern',Name,Value)
newt = coder.cstructname(t,'structName')
newt = coder.cstructname(t,'structName','extern')
newt = coder.cstructname(t,'structName','extern',Name,Value)

Description

coder.cstructname(var,'structName') specifies the name of the structure type that represents var in the generated C/C++ code. var is a structure or cell array variable. structName is the name for the structure type in the generated code. Use this syntax in a function from which you generate code. Call coder.cstructname before the first use of the variable. If var is a cell array element, call coder.cstructname after the first assignment to the element.

coder.cstructname(var,'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(var,'structName','extern',Name,Value) uses additional options specified by one or more Name,Value pair arguments.

newt = coder.cstructname(t,'structName') returns a copy of the type object specified by t. The copy specifies the name structName to use for the structure type that represents t in the generated code. t is a coder.StructType object or a coder.CellType object. Use this syntax to create a type that you use with the fiaccel -args option. You cannot use this syntax in a function from which you generate code.

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

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

Limitations

  • You cannot use coder.cstructname with global variables.

  • If var is a cell array or t is a coder.CellType object, the field names of externally defined structures must be f1, f2, and so on.

  • If var is a cell array element, call coder.cstructname after the first assignment to the element. For example:

    ...
    x = cell(2,2);
    x{1} = struct('a', 3);
    coder.cstructname(x{1}, 'mytype');
    ...

Tips

  • The code generator represents a heterogeneous cell array as a structure in the generated C/C++ code. To specify the name of the generated structure type, use coder.cstructname.

  • Using coder.cstructname with a homogeneous coder.CellType object t makes the returned object heterogeneous unless t is permanently homogeneous. If the makeHomogeneous method created t or if t is variable size,t is permanently homogeneous.

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

  • In a function from which you generate code, using coder.cstructname with a cell array variable makes the cell array heterogeneous. Unless the cell array type is permanently set to homogeneous, you can use coder.cstructname with an entry-point function input that is a cell array.

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

  • 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 of the structure type in the generated code.

t

coder.StrucType object or coder.CellType object.

var

Structure or cell array 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 character vector or string scalar.

Output Arguments

newt

coder.StrucType object or coder.CellType object.

Examples

collapse all

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;

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. So that TopVar has the same type as top, generate C code for MyFunc with an argument having 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.type 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.type 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 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.type 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 generator does not generate the definition of mytype. Instead the software includes the header file, MyFile.h, in the generated code.

Create a coder.CellType object for a cell array whose first element is char and whose second element is double.

T = coder.typeof({'c', 1})
T = 

coder.CellType
   1x2 heterogeneous cell 
      f0: 1x1 char
      f1: 1x1 double

T is a heterogeneous coder.CellType object.

Create a copy of T that specifies the name myname for the structure type that represents T in the generated code.

T = coder.cstructname(T, 'myname')
coder.CellType
   1x2 heterogeneous cell myname
      f0: 1x1 char
      f1: 1x1 double

Write a function struct_in_cell that has a cell array x{1} that contains a structure. The coder.cstructname call follows the assignment to x{1}.

function z = struct_in_cell()
x = cell(2,2);
x{1} = struct('a', 3);
coder.cstructname(x{1}, 'mytype');
z = x{1};
end

Generate a static library for struct_in_cell.

codegen -config:lib struct_in_cell -report

The type for a has the name mytype.

 typedef struct {
  double a;
} mytype;

Introduced in R2011a

Was this topic helpful?