MATLAB®

Working with Structures

Structure Argument Requirements

For library functions that take structure arguments, you need to pass structures that have field names that are the same as those in the structure definitions in the library.

The following guidelines apply to MATLAB structures passed to external library functions:

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

• Every structure field name you use must match a field name in the structure definition. Structure names are case sensitive.

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

When you create and initialize the structure, you do not necessarily have to match the data types of numeric fields. MATLAB converts to the correct numeric type for you when you make the call using the calllib function.

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 names and data types of structure fields, you can:

• Consult the library documentation.

• Look at the structure definition in the header file you used to load the library into MATLAB.

• Use the libstruct, as described in Example of Finding Structure Field Names.

Example of Finding Structure Field Names

You can also determine the field names of an externally defined structure from MATLAB using the following procedure.

1. Use libfunctionsview to display the signatures for all functions in the library. libfunctionsview shows the names of the structures used by each function. For example, when you type:

   libfunctionsview shrlibsample

   MATLAB opens a window displaying function signatures for the shrlibsample library. The line showing the addStructFields function reads:

   double addStructFields (c_struct)

2. If the function you are using takes a structure argument, get the structure type from the libfunctionsview display, and invoke the libstruct function on that type. libstruct returns an object that is modeled on the structure as defined in the library:

   s = libstruct('c_struct');

3. To get the names of the structure fields from the object returned by libstruct, type:

   get(s)
   

   MATLAB displays:

       p1: 0 
       p2: 0 
       p3: 0

4. Initialize the fields to the values you want to pass to the library function and make the call using calllib:

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

Back to Top

Example of Passing a MATLAB Structure

As with other data types, when an external function takes a structure argument (such as a C structure), you can pass a MATLAB structure to the function in its place.

The sample shared library, shrlibsample, defines the following C structure and function:

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;
}

The following example passes a MATLAB structure to addStructFields. To load the library, type:

if not(libisloaded('shrlibsample'))
  addpath([matlabroot '\extern\examples\shrlib']);
  loadlibrary shrlibsample shrlibsample.h;
end

Create the structure, sm, with three double fields. MATLAB converts the fields to the double, short, and long data types defined in the C structure, c_struct. For example, type

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

MATLAB displays:

ans =
        1177

Back to Top

Passing a libstruct Object

• Preconverting a MATLAB Struct with libstruct

• Creating an Empty libstruct Object

• libstruct Requirements for Structures

• Example of Passing a libstruct Object

When you pass a structure to an external function, MATLAB makes sure that the structure being passed matches the library's definition for that structure type. It must contain all the necessary fields defined for that type and each field must be of the expected data type. For any fields that are missing in the structure being passed, MATLAB creates an empty field of that name and initializes its value to zero. For any fields that have a data type that doesn't match the structure definition, MATLAB converts the field to the expected type.

When working with small structures, it is efficient enough to have MATLAB do this work for you. You can pass the original MATLAB structure with calllib and let MATLAB handle the conversions automatically. 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.

Preconverting a MATLAB Struct with libstruct

You can convert a MATLAB structure to a C-style structure derived from a specific type definition in the library in one step. Call the libstruct function, passing in the name of the structure type from the library, and the original structure from MATLAB. The syntax for libstruct is:

s = libstruct('structtype', mlstruct)

The value s returned by this function is called a libstruct object. Although it is a MATLAB object, it behaves like a MATLAB structure. The fields of this new "structure" are derived from the external structure type specified by structtype in the syntax above.

For example, to convert a MATLAB structure, sm, to a libstruct object, sc, that is derived from the c_struct structure type, 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, returned from the libstruct function, has fields that match the c_struct structure type. These fields are double, short, and long.

Note   You can only use libstruct on scalar structures.

Creating an Empty libstruct Object

You can create an empty libstruct object by calling libstruct with only the structtype argument. For a type specified by structtype, the following syntax constructs an object with all the required fields and with each field initialized to zero:

s = libstruct('structtype')

libstruct Requirements for Structures

When converting a MATLAB structure to a libstruct object, the structure to be converted must adhere to the same guidelines that were documented for MATLAB structures passed directly to external functions. See Structure Argument Requirements.

Example of Passing a libstruct Object

Repeat the addStructFields example, this time converting the structure to one of type c_struct before calling the function:

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, passing the structure sc:

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

MATLAB displays:

ans =
    1177

Compare this example with Example of Passing a MATLAB Structure.

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 lib.c_struct Object

• Accessing lib.c_struct Fields

The value returned by libstruct is not a MATLAB structure. It is an instance of a class called lib.c_struct, as seen by examining the output of whos. 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 lib.c_struct Object

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

sc.structsize

MATLAB displays:

ans = 
		16

Accessing lib.c_struct Fields

The fields of this structure are implemented as 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