External Interfaces Reference |
Create 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 ndim
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.
Structure field names must begin with a letter, and are case-sensitive. The rest of the name may contain letters, numerals, and underscore characters. Use the namelengthmax
function to determine the maximum length of a field name.
Returns
A pointer to the created structure mxArray
if successful, and NULL
otherwise. 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.
Any trailing singleton dimensions specified in the dims
argument are automatically removed from the resulting array. For example, if ndim
equals 5
and dims
equals [4 1 7 1 1]
, the resulting array is given the dimensions 4-by-1-by-7.
Examples
See mxcreatestructarray.c
in the mx
subdirectory of the examples
directory.
See Also
mxDestroyArray
, mxSetNzmax
, namelengthmax
mxCreateString | mxCreateStructMatrix |
© 1994-2005 The MathWorks, Inc.