Main Content

mxCreateStructArray (Fortran)

N-D structure array

Fortran Syntax

#include "fintrf.h"
mwPointer mxCreateStructArray(ndim, dims, nfields, fieldnames)
mwSize ndim
mwSize dims(ndim)
integer*4 nfields
character*(*) fieldnames(nfields)

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.

Each field holds one mxArray pointer initialized to 0. Call mxSetField or mxSetFieldByNumber to place a non-0 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. The mxDestroyArray function deallocates 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 ndim array of 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(1) to 5 and dims(2) to 7.

Usually, the dims array contains ndim elements.

Number of fields in each element, specified as integer*4.

One or more field names, specified as character*(*).

Field names must be valid MATLAB® identifiers, which means they cannot be 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 mwPointer.

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 0.

Version History

Introduced before R2006a