Pass struct Parameter

Pass `struct` Parameter

You can pass a MATLAB^® structure as a parameter to a C++ function. The MATLAB interface to the C++ library converts the structure to a C++ struct argument. Likewise, you can configure a C++ function to return a C++ struct as a MATLAB structure. The MATLAB structure must meet these requirements.

The structure contains all the fields of the C++ structure definition.
The field names of the structure must exactly match the field names of the C++ structure. Field names are case-sensitive.
The MATLAB structure cannot contain fields that are not in the C++ structure.
The data type for each field value must be a valid type for the matching field in the C++ structure.
The size of the field value must match the C++ data member size.

Return MATLAB `struct` Example

This example shows how to configure an interface to functions that return a struct as either a C++ struct of type A or as a MATLAB struct.

Display Help for `struct` Example

Suppose that you have an interface defined by this code with functions returnClib and returnMATLABStruct that return a struct A.

struct A { int I; };

A returnClib();
A returnMATLABStruct();

To run this example, follow the instructions in Build Interface for struct Example to generate a MATLAB interface named lib.

When you display help for lib, you see that it contains a class A and functions returnClib and returnMATLABStruct.

help clib.lib

Classes contained in clib.lib:
A                              -  clib.lib.A    Representation of C++ class A.


Functions contained in clib.lib:
returnMATLABStruct             -  clib.lib.returnMATLABStruct Representation of C++ function returnMATLABStruct.

returnClib                     -  clib.lib.returnClib Representation of C++ function returnClib.

Display help for the functions.

help clib.lib.returnMATLABStruct

returnMATLABStruct -  clib.lib.returnMATLABStruct Representation of C++ function returnMATLABStruct.

  RetVal = clib.lib.returnMATLABStruct
    Output Arguments
      RetVal         struct with fields: 
                      I              int32

help clib.lib.returnClib

returnClib -  clib.lib.returnClib Representation of C++ function returnClib.

  RetVal = clib.lib.returnClib
    Output Arguments
      RetVal         clib.lib.A

Display help for A.

help clib.lib.A

A -  clib.lib.A    Representation of C++ class A.

      struct with fields:  
      I              int32

Call `returnMATLABStruct` and `returnClibreturnMATLABStruct`

The returnMATLABStruct function returns an object you can use as a MATLAB struct.

mobj = clib.lib.returnMATLABStruct

mobj = 

  struct with fields:

    I: 10

The returnClib function returns an object of struct A. You can pass this object to other functions in the library that accept A parameters.

cobj = clib.lib.returnClib

cobj = 

  A with properties:

    I: 10

Build Interface for `struct` Example

This C++ code defines two functions that return struct A.

#include <utility>
struct A { int I; };

A returnClib(){
    A a1{10}; 
    return std::move(a1);
};

A returnMATLABStruct(){
    A a1{10}; 
    return std::move(a1);
};

Save this code in a header file named lib.hpp, then generate a library definition file for a MATLAB interface named lib following the instructions in Header-Only HPP File.

For this example, edit the library definition file definelib.m and define the return arguments RetVal as:

returnClib function—By default, the <MLTYPE> is "clib.lib.A". Do not edit this value.
returnMATLABStruct function—Change the <MLTYPE> from "clib.lib.A" to "struct".

Library Artifacts	MATLAB Interface `libname`	MATLAB Help
Header file `lib.hpp`	`clib.lib`	`>> help clib.lib`

Pass `nullptr` Parameter Example

This example shows how to assign nullptr values to a MATLAB struct to pass to a function in a C++ library.

Display Help for `clib.libnullptr`

Suppose that you have an interface with the struct definition MyStruct. To run this example, follow the instructions in Build Interface for nullptr Example to generate a MATLAB interface named libnullptr.

When you display help for libnullptr, you see that it contains classes MyStruct and Inner.

help clib.libnullptr

Classes contained in clib.libnullptr:
Inner                          -  clib.libnullptr.Inner    Representation of C++ class Inner.

MyStruct                       -  clib.libnullptr.MyStruct    Representation of C++ class MyStruct.

Display the help text for MyStruct.

help clib.lib.MyStruct

MyStruct -  clib.lib.MyStruct    Representation of C++ class MyStruct.

      struct with fields:  
      in1            struct with fields:
                     i              int32

      in2            2 element vector struct with fields:
                     i              int32



    Documentation for clib.lib.MyStruct

Display the help text for Inner.

help clib.lib.Inner

Inner -  clib.lib.Inner    Representation of C++ class Inner.

      struct with fields:  
      i              int32


    Documentation for clib.lib.Inner

Set Pointer Fields to `nullptr`

Create a MATLAB object myStruct. Use single quotes to assign an empty value to the char* field str.

myStruct.str = '';

Assign empty to numeric field x.

myStruct.x = int32.empty;

Assign [] to struct pointer data member in1.

myStruct.in1 = struct([]);

Alternatively, you can assign empty to the field.

myStruct.in1 = struct.empty;

Create an object.

obj = clib.libnullptr.MyStruct(myStruct)

obj = 
  MyStruct with properties:

    str: [0×0 string]
      x: [1×1 clib.array.lib.Int]
    in1: [1×1 clib.lib.Inner]

You can convert this C++ struct with pointer fields set to nullptr to a MATLAB structure mlStruct using the struct function.

mlStruct = struct(obj)

mlStruct = struct with fields:
    str: ''
      x: []
    in1: [1×1 struct]

Build Interface for `nullptr` Example

This C++ code defines MyStruct with data members that point to struct Inner:

#include <stdint.h>
struct Inner { int i; };
struct MyStruct { 
    char *str;
    int32_t *x;
    Inner *in1;
};

Save this code in a header file named MyStruct.hpp, then generate a library definition file for a MATLAB interface named libnullptr following the instructions in Header-Only HPP File.

The MyStruct class needs definition based on your implementation. For this example, edit the library definition file definelibnullptr.m and define the input arguments as:

Argument str—Set <MLTYPE> to "string" and <SHAPE> to "nullTerminated".
Argument x—Set <MLTYPE> to "clib.array.lib.Int32".
Argument in1—Set <MLTYPE> to clib.lib.Inner.

Library Artifacts	MATLAB Interface `libname`	MATLAB Help
Header file `MyStruct.hpp`	`clib.libnullptr`	`>> help clib.libnullptr`