Pass struct Parameter
R2026bYou 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.libClasses 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.returnMATLABStructreturnMATLABStruct - clib.lib.returnMATLABStruct Representation of C++ function returnMATLABStruct.
RetVal = clib.lib.returnMATLABStruct
Output Arguments
RetVal struct with fields:
I int32help clib.lib.returnClibreturnClib - 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.AA - clib.lib.A Representation of C++ class A.
struct with fields:
I int32Call 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: 10The 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: 10Build 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 Publish MATLAB Interface Using Live Script Workflow.
For this example, edit the library definition file
definelib.m and define the return arguments
RetVal as:
returnClibfunction—By default, the<MLTYPE>is"clib.lib.A". Do not edit this value.returnMATLABStructfunction—Change the<MLTYPE>from"clib.lib.A"to"struct".
| Library Artifacts | MATLAB Interface
libname | MATLAB Help |
|---|---|---|
Header file |
|
|
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.libnullptrClasses 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.MyStructMyStruct - 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.MyStructDisplay the help text for Inner.
help clib.lib.InnerInner - clib.lib.Inner Representation of C++ class Inner.
struct with fields:
i int32
Documentation for clib.lib.InnerSet 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 Publish MATLAB Interface Using Live Script Workflow.
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>toclib.lib.Inner.
| Library Artifacts | MATLAB Interface
libname | MATLAB Help |
|---|---|---|
Header file
|
|
|
