MATLAB Application Program Interface Reference

Create an unpopulated N-dimensional cell mxArray

#include "matrix.h"
mxArray *mxCreateCellArray(int ndim, const int *dims);

Arguments

ndim

The desired number of dimensions in the created cell. For example, to create a three-dimensional cell mxArray, set ndim to 3.

dims

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.

Returns

A pointer to the created cell 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

Insufficient free heap space.
Specifying a value for ndim that is greater than the number of values in the dims array.

Description

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

Examples

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.