MATLAB Application Program Interface Reference | Help Desk |
mxCreateCellArray
Create an unpopulated N-dimensional cellmxArray
#include "matrix.h" mxArray *mxCreateCellArray(int ndim, const int *dims);ndim
The desired number of dimensions in the created cell. For example, to create a three-dimensional cell mxArray
, set ndim
to 3.
The dimensions array. Each element in the dimensions array contains the size of the mxArray
in that dimension. For example, setting dims[0]
to 5 and dims[1]
to 7 establishes a 5-by-7 mxArray
. In most cases, there should be ndim
elements in the dims
array.
mxArray
, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCellArray
returns NULL
. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Causes of failure include
ndim
that is greater than the number of values in the dims
array.
mxCellArray
to create a cell mxArray
whose size is defined by ndim
and dims
. For example, to establish a three-dimensional cell mxArray
having dimensions 4-by-8-by-7, set
ndim = 3; dims[0] = 4; dims[1] = 8; dims[2] = 7;The created cell
mxArray
is unpopulated; that is, mxCreateCellArray
initializes each cell to NULL
. To put data into a cell, call mxSetCell
.
Create a two-dimensional 2-by-2 cell mxArray
named amoeba
, then populate two of its 4 cells:
int ndim=2, dims[]={2, 2}; int index, nsubs=2, subs[2]; double real_pr[] = {5.23, 7.45, 8.17, 9.79}; double *pr; mxArray *cell_array_ptr, *string_array_ptr, *vector_ptr; /* Create a 2-by-2 cell array. */ cell_array_ptr = mxCreateCellArray(ndim, dims); mxSetName(cell_array_ptr, "amoeba"); /* Create a string array. */ string_array_ptr = mxCreateString("Hello friends."); /* Place the string array into cell element (1,1). */ subs[0]=0; subs[1]=0; index = mxCalcSingleSubscript(cell_array_ptr, nsubs, subs); mxSetCell(cell_array_ptr, index, string_array_ptr); /* Create a 1-by-4 vector array of doubles. */ vector_ptr = mxCreateDoubleMatrix(1, 4, mxREAL); pr = mxGetPr(vector_ptr); memcpy((void *)pr,(const void *)real_pr,4*sizeof(double)); /* Place the vector array into cell element (2,2). */ subs[0]=1; subs[1]=1; index = mxCalcSingleSubscript(cell_array_ptr, nsubs, subs); mxSetCell(cell_array_ptr, index, vector_ptr);The code leaves cell array elements
(1,2)
and (2,1)
unpopulated.
For an additional example, see mxCreateCellArray.c
in the mx
subdirectory of the examples
directory.
mxCreateCellMatrix
, mxGetCell
, mxSetCell
, mxIsCell