MATLAB Application Program Interface Reference Help Desk

mxCreateStructArray

Purpose

Create an unpopulated N-dimensional structure mxArray

C Syntax

Arguments

ndim

Number of dimensions. If you set ndims to be less than 2, mxCreateNumericArray creates a two-dimensional mxArray.

dims

The dimensions array. Each element in the dimensions array contains the size of the array in that dimension. For example, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. Typically, the dims array should have ndim elements.

nfields

The desired number of fields in each element.

field_names

The desired list of field names.

Returns

A pointer to the created structure mxArray, if successful; otherwise, returns NULL. The most likely cause of failure is insufficient heap space to hold the returned mxArray.

Description

Call mxCreateStructArray to create an unpopulated structure mxArray. Each element of a structure mxArray contains the same number of fields (specified in nfields). Each field has a name; the list of names is specified in field_names. A structure mxArray in MATLAB is conceptually identical to an array of structs in the C language.

Each field holds one mxArray pointer. mxCreateStructArray initializes each field to NULL. Call mxSetField or mxSetFieldByNumber to place a non-NULL mxArray pointer in a field.

When you finish using the returned structure mxArray, call mxDestroyArray to reclaim its space.

Examples

Create a 2-by-3 structure mxArray, in which each element contains two fields (the "name" field and the "grade" field). Then, populate the field with data. Each "name" field holds a string mxArray and each "grade" field holds a numeric mxArray.

For an additional example, see mxCreateStructArray.c in the mx subdirectory of the examples directory.

See Also

mxCreateFull, mxDestroyArray, mxSetNzmax



[ Previous | Help Desk | Next ]