mxCreateStructArray (C)

N-D structure array

expand all in page

C Syntax

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

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, specified in fieldnames. A MATLAB® structure mxArray is conceptually identical to an array of structs in the C language.

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

The function automatically removes trailing singleton dimensions specified in the dims argument. For example, if ndim equals 5 and dims equals [4 1 7 1 1], then the dimensions of the resulting array are 4-by-1-by-7.

Call mxDestroyArray when you finish using the mxArray to deallocate the mxArray and its associated elements.

Input Arguments

expand all

Number of dimensions, specified as mwSize. If ndim is less than 2, then mxCreateStructArray sets the number of dimensions to 2.

Dimensions array, specified as an array of const mwSize.

Each element in the dimensions array contains the size of the array in that dimension. For example, to create a 5-by-7 array, set dims[0] to 5 and dims[1] to 7.

Usually, the dims array contains ndim elements.

Number of fields in each element, specified as int.

One or more field names, specified as const char **.

Field names must be valid MATLAB identifiers, which means they cannot be NULL or empty. Field names are case-sensitive. To determine the maximum length of a field name, use the namelengthmax function.

Output Arguments

expand all

Pointer to an mxArray, specified as mxArray *.

The function is unsuccessful when there is not enough free heap space to create the mxArray.

  • MEX file — Function terminates the MEX file and returns control to the MATLAB prompt.

  • Standalone (non-MEX file) application — Function returns NULL.

Examples

To open an example, type:

edit([fullfile(matlabroot,"extern","examples","mx","filename")]);

where filename is:

Version History

Introduced before R2006a

See Also

| | | | |