Pass Structures Examples

The shrlibsample example library contains two functions with c_struct structure input parameters. c_struct is defined in the shrlibsample.h header file.

struct c_struct {
double p1;
short p2;
long  p3;
};

Both functions sum the values of the fields in the structure. The input to addStructFields is c_struct. The input to addStructByRef is a pointer to c_struct. This function also modifies the fields after summing the values.

The addStructFields function sums the values of the fields in a c_struct structure.

{
double t = st.p1 + st.p2 + st.p3;
return t;
}

The MATLAB® function signature is:

Return TypeNameArguments

The addStructByRef function sums the values of the fields in a c_struct structure, then modifies the fields. The function returns the sum calculated before modifying the fields.

EXPORTED_FUNCTION double addStructByRef(struct c_struct *st) {
double t = st->p1 + st->p2 + st->p3;
st->p1 = 5.5;
st->p2 = 1234;
st->p3 = 12345678;
return t;
}

Since the function modifies the input argument, MATLAB also returns the input as an output argument of type c_structPtr. The MATLAB function signature is:

Return TypeNameArguments
[double,
c_structPtr]

You can pass a MATLAB structure to the function and let MATLAB autoconvert the argument. Or you can pass a pointer to a structure, which avoids creating a copy of the structure.

Add Values of Fields in Structure

This example shows how to pass a MATLAB structure to the function, addStructFields.

Create and initialize structure sm. Each field is of type double.

sm.p1 = 476;
sm.p2 = -299;
sm.p3 = 1000;

end

Call the function. MATLAB automatically converts the fields of structure sm to the library definition for c_struct.

ans = 1177

Preconvert MATLAB Structure Before Adding Values

This example shows how to preconvert structure sm to c_struct before calling addStructFields. If you repeatedly pass sm to functions, preconverting eliminates the processing time required by MATLAB to autoconvert the structure for each function call.

Create and initialize a MATLAB structure.

sm.p1 = 476;
sm.p2 = -299;
sm.p3 = 1000;

end

Convert the fields, which are of type double, to match the c_struct structure types, double, short, and long.

sc = libstruct('c_struct',sm);

Display the field names and values.

get(sc)
p1: 476
p2: -299
p3: 1000

ans = 1177

Autoconvert Structure Arguments

This example shows how to pass a MATLAB structure to a C library function, addStructByRef. When you pass the structure, MATLAB automatically converts the field types, but MATLAB also makes a copy of the fields.

end

Create a structure.

S.p1 = 476;
S.p2 = -299;
S.p3 = 1000;

res = 1177

MATLAB does not modify the contents of structure S, since it is not a pointer.

S
S = struct with fields:
p1: 476
p2: -299
p3: 1000

Pass Pointer to Structure

This example shows how calling the addStructByRef function with a pointer modifies the fields in the input argument.

end

Create a structure of type c_struct.

S.p1 = 20;
S.p2 = 99;
S.p3 = 3;

Create a pointer sp to the structure.

sp = libpointer('c_struct',S);
sp.Value
ans = struct with fields:
p1: 20
p2: 99
p3: 3

Pass the pointer to the function.

res = 122

When you pass a pointer, the function modifies the fields in the structure it points to.

sp.Value
ans = struct with fields:
p1: 5.5000
p2: 1234
p3: 12345678