Pass Structures Examples

addStructFields and addStructByRef Functions

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.

addStructFields Function

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

EXPORTED_FUNCTION double addStructFields(struct c_struct st)
{
    double t = st.p1 + st.p2 + st.p3;
    return t;
}

The MATLAB^® function signature is:

Return Type	Name	Arguments
double	addStructFields	(struct c_struct)

addStructByRef Function

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 Type	Name	Arguments
[double, c_structPtr]	addStructByRef	(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;

Load the library containing the addStructFields function.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

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

calllib('shrlibsample','addStructFields',sm)

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;

Load the library containing the addStructFields function.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
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

Add the field values.

calllib('shrlibsample','addStructFields',sc)

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.

Load the library.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Create a structure.

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

Call addStructByRef.

res = calllib('shrlibsample','addStructByRef',S)

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.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
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 = calllib('shrlibsample','addStructByRef',sp)

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