Using the C Math Library

Creating Structures

The MATLAB C Math Library allows you to create structures by:

• Using a structure creation routine
• Using a structure conversion routine
• Assigning a value to an element in a structure

Using a Structure Creation Routine

You can create a structure using the mlfStruct() routine. This routine lets you define the fields in the structure and assign a value to each field. For example, the following code fragment creates a structure that contains two fields, a text string and a scalar value.

mxArray *A = NULL;

mlfAssign(&A, mlfStruct(mxCreateString("name"),   /* Field */
                        mxCreateString("John"),   /* Value */
                        mxCreateString("number"), /* Field */
                        mlfScalar(311),           /* Value */
                        NULL));

mlfPrintMatrix(A);

mlfDestroyArray(A)

This code produces the following output:

  name: 'John'
number: 311

Because the mlfStruct() routine can accept a varying number of input arguments, you must terminate the argument list with a NULL.

Creating Multidimensional Arrays of Structures

The mlfstruct() routine defines the fields and values in a single instance of a structure, in effect a 1-by-1 structure array. To create a multidimensional array of structures, use MATLAB indexing to assign a value to a field in a structure with an index other than (1,1). MATLAB will extend the array of structures to accommodate the location specified. For more information about using assignment with structures, see Using Assignment to Create Structures.

Using a Structure Conversion Routine

You can also create structures by converting an existing MATLAB cell array into a structure, using the mlfCell2struct() routine. This example creates a cell array to be converted, and a second cell array that specifies the names of the fields in the structure. You pass these two cell arrays, along with the dimensions of the structure array, as arguments to mlfCell2struct().

mxArray *C = NULL; /* cell array to convert */
mxArray *F = NULL; /* cell array of field names */
mxArray *S = NULL; /* structure   */

/* create cell array to be converted */
mlfAssign(&C, mlfCellhcat(mxCreateString("tree"),
                          mlfScalar(37.4),
                          mxCreateString("birch"),
                          NULL));          

/* create cell array of field names */
mlfAssign(&F, mlfCellhcat(mxCreateString("category"),
                          mxCreateString("height"),
                          mxCreateString("name"),
                          NULL));          

/* convert cell array to structure */
mlfAssign(&S,mlfCell2struct(C,F,mlfScalar(2)));

mlfPrintMatrix(C);
mlfPrintMatrix(S);

mlfDestroyArray(C);
mlfDestroyArray(F);
mlfDestroyArray(S);

Note that, because mlfCellhcat() accepts a variable number of input arguments, you must terminate the input argument list with a NULL.

This code generates the following output.

'tree'    [37.4000]    'birch'

category: 'tree'
  height: 37.4000
    name: 'birch'

Using Assignment to Create Structures

You can also create a structure by assigning a value to a location in a structure, using the mlfIndexAssign() routine. The MATLAB C Math Library creates a structure (or array of structures) large enough to accommodate the location specified by the index string. For more information about structure indexing, see Chapter 5.

The following example is equivalent to the MATLAB statement,
A(2) = struct('name','jim','number',312).

mxArray *A = NULL;

mlfIndexAssign(&A, 
               "(?)",        /* Index subscript format string  */
               mlfScalar(2), /* Index subscript value */
               mlfStruct(mxCreateString("name"),  /* Field */
                         mxCreateString("Jim"),   /* Value */
                         mxCreateString("number"),/* Field */
                         mlfScalar(312),          /* Value */
                         NULL)); 
    
mlfPrintMatrix(A);

mlfDestroyArray(A);

The following output shows the structure created by this code fragment.

1x2 struct with fields
    name
    number

For more detailed information about using mlfIndexAssign() to assign values to fields in a structure, see Chapter 5.

MATLAB Structures

Performing Common Array Programming Tasks