mxCreateStructArray (MATLAB Application Program Interface)

Create an unpopulated N-dimensional structure mxArray

C Syntax

#include "matrix.h"
mxArray *mxCreateStructArray(int ndim, const int *dims, int nfields,
         const char **field_names);

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.

Example

See mxcreatestructarray.c in the mx subdirectory of the examples directory.