Documentation Center

  • Trial Software
  • Product Updates

mxCreateCellArray (C and Fortran)

N-D cell array

C Syntax

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

Fortran Syntax

mwPointer mxCreateCellArray(ndim, dims)
mwSize ndim
mwSize dims(ndim)

Arguments

ndim

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

dims

Dimensions array. Each element in the dimensions array contains the size of the mxArray in that dimension. For example, in C, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. In Fortran, setting dims(1) to 5 and dims(2) to 7 establishes a 5-by-7 mxArray. In most cases, there should be ndim elements in the dims array.

Returns

Pointer to the created mxArray, if successful. If unsuccessful in a standalone (non-MEX-file) application, returns NULL in C (0 in Fortran). If unsuccessful in a MEX-file, the MEX-file terminates and returns control to the MATLAB® prompt. The function is unsuccessful when there is not enough free heap space to create the mxArray.

Description

Use mxCreateCellArray to create a cell mxArray with size defined by ndim and dims. For example, in C, 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;

In Fortran, to establish a three-dimensional cell mxArray having dimensions 4-by-8-by-7, set:

ndim = 3;
dims(1) = 4; dims(2) = 8; dims(3) = 7;

The created cell mxArray is unpopulated; mxCreateCellArray initializes each cell to NULL. To put data into a cell, call mxSetCell.

MATLAB automatically removes any trailing singleton dimensions specified in the dims argument. For example, if ndim equals 5 and dims equals [4 1 7 1 1], the resulting array has the dimensions 4-by-1-by-7.

Examples

See the following examples in matlabroot/extern/examples/refbook.

Was this topic helpful?