Learn more about MATLAB

Working with Structures

On this page…
Structure Argument Requirements Working with Structures Examples Finding Structure Field Names Example of Passing a MATLAB Structure Passing a libstruct Object Using the Structure as an Object

Structure Argument Requirements

When you pass a MATLAB structure to an external library function:

• Every MATLAB field name must match a field name in the library structure definition. Field names are case sensitive.

• MATLAB structures cannot contain fields that are not in the library structure definition.

• If a MATLAB structure contains fewer fields than defined in the library structure, MATLAB sets undefined fields to zero.

You do not need to match the data types of numeric fields. The calllib function converts to the correct numeric type.

Back to Top

Working with Structures Examples

[instructions for opening shrlibsample code]

Examples in this topic are:

• Example of Finding Structure Field Names

• Example of Passing a MATLAB Structure

• Example of Passing a libstruct Object

• Using the Structure as an Object

Back to Top

Finding Structure Field Names

To determine the name and data type of structure fields, you can:

• Consult the library documentation.

• Look at the structure definition in the library header file.

• Use the libstruct function, as described in the following example.

Example of Finding Structure Field Names

You can determine the field names of an externally defined structure using the libstruct function. For example, look at the addStructFields function in the shrlibsample library. It has the signature:

double addStructFields (c_struct)

Create a libstruct object:

s = libstruct('c_struct');

To get the names of the fields, type:

get(s)

MATLAB displays the field names and their values:

    p1: 0 
    p2: 0 
    p3: 0

To set the field values, type:

s.p1 = 476;   s.p2 = -299;   s.p3 = 1000;
calllib('shrlibsample','addStructFields',s);
get(s)

MATLAB displays:

    p1: 476
    p2: -299
    p3: 1000

Back to Top

Example of Passing a MATLAB Structure

The following example passes a MATLAB structure to the addStructFields function in the shrlibsample library. The library defines the following:

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

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

To load the library, type:

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

Create a structure, sm, with three fields of type double:

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

The calllib function converts the fields to the double, short, and long data types defined in c_struct:

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

MATLAB displays:

ans =
        1177

Back to Top

Passing a libstruct Object

When working with small structures, you can let MATLAB convert the structure being passed to the library definition for that structure type, as described in Structure Argument Requirements. However, when working with repeated calls that pass one or more large structures, it may be to your advantage to convert the structure manually before making any calls to external functions. In this way, you save processing time by converting the structure data only once at the start rather than at each function call. You can also save memory if the fields of the converted structure take up less space than the original MATLAB structure. You do this by creating a libstruct object, as described in the following topics:

• Preconverting a MATLAB Structure with libstruct

• Creating an Empty libstruct Object

• libstruct Requirements for Structures

• Example of Passing a libstruct Object

Preconverting a MATLAB Structure with libstruct

Use the libstruct function to convert a MATLAB structure to a C-style structure. The syntax for libstruct is:

s = libstruct('structtype', mlstruct)

The variable s is a libstruct object. Although it is an object, it behaves like a MATLAB structure. The fields of the object are derived from the external structure type specified by structtype.

For example, to convert a MATLAB structure, sm, to a libstruct object, sc, type:

sm.p1 = 476;   sm.p2 = -299;   sm.p3 = 1000;
sc = libstruct('c_struct', sm);

All of fields in the original structure sm are of type double. The object sc has fields that match the c_struct structure type. These fields are double, short, and long. Type:

get(sc)

MATLAB displays:

    p1: 476
    p2: -299
    p3: 1000

Note   You can only use the libstruct function on scalar structures.

Creating an Empty libstruct Object

To create an empty libstruct object, call libstruct with only the structtype argument. For example:

sci = libstruct('c_struct')
get(sci)

MATLAB displays the initialized values:

    p1: 0
    p2: 0
    p3: 0

libstruct Requirements for Structures

When converting a MATLAB structure to a libstruct object, the structure must adhere to the requirements listed in Structure Argument Requirements.

Example of Passing a libstruct Object

Compare the following example with the Example of Passing a MATLAB Structure. Convert structure sm to type c_struct:

sm.p1 = 476;   sm.p2 = -299;   sm.p3 = 1000;
sc = libstruct('c_struct', sm);
get(sc)

MATLAB displays:

    p1: 476
    p2: -299
    p3: 1000

Now call the function with the libstruct object sc:

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

MATLAB displays:

ans =
    1177

Note   When passing manually converted structures, the structure passed must be of the same type as that used by the external function. For example, you cannot pass a structure of type records to a function that expects type c_struct.

Back to Top

Using the Structure as an Object

• Determining the Size of a libstruct Object

• Accessing Fields of a libstruct Object

A libstruct object is not a MATLAB structure. It is an instance of a class called lib.c_struct. Type:

whos

MATLAB displays (in part):

  Name      Size                   Bytes  Class

sc         1x1                           lib.c_struct
sm         1x1                      396  struct array

Determining the Size of a libstruct Object

You can use the lib.c_struct class method structsize to obtain the size of a libstruct object:

sc.structsize

MATLAB displays:

ans = 
		16

Accessing Fields of a libstruct Object

The fields of this structure are properties of the lib.c_struct class. You can read and modify any of these fields using the MATLAB object-oriented functions, set and get:

sc = libstruct('c_struct');
set(sc, 'p1', 100, 'p2', 150, 'p3', 200);
get(sc)

MATLAB displays:

    p1: 100
    p2: 150
    p3: 200

You can read and modify the fields by treating them like MATLAB structure fields:

sc.p1 = 23;
sc.p1

MATLAB displays:

ans =
   23

Back to Top

Working with Pointers

Calling C and Fortran Programs from MATLAB Command Line

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS