mxGetCell (MATLAB Application Program Interface)

Get a cell's contents

#include "matrix.h"
mxArray *mxGetCell(const mxArray *array_ptr, int index);

Arguments

array_ptr
Pointer to a cell mxArray.

index
The number of elements in the cell mxArray between the first element and the desired one. See mxCalcSingleSubscript for details on calculating an index.

Returns

A pointer to the ith cell mxArray, if successful; otherwise, returns NULL. Causes of failure include

Insufficient free heap space to hold the returned cell mxArray.
Specifying an array_ptr that does not point to a cell mxArray.
Specifying an index greater than the number of elements in the cell.

Description

Call mxGetCell to get a pointer to the mxArray held in the indexth element of the cell mxArray. Note: Changing data contained within the cell may cause unpredictable results.

Examples

Consider a MEX-file named OneTwo that calls mxGetCell to get the (1,2) cell of an input cell mxArray. If cell (1,2) contains a string mxArray, the MEX-file converts its data to C string format.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 int       nsubs=2, subs[]={0, 1}, index, buflen, status;
 mxArray  *cell_element_ptr;
 char     *buf;

 /* Is the first input argument a cell mxArray. */
   if (mxIsCell(prhs[0])) {

     /* Get the cell at (1,2). */
       index = mxCalcSingleSubscript(prhs[0], nsubs, subs); 
       cell_element_ptr = mxGetCell(prhs[0], index);

     /* If the cell at (1,2) holds a string, print the string. */ 
       if (mxIsChar(cell_element_ptr))  {
 
         /* Find out how long the input string array is. */
           buflen = (mxGetM(cell_element_ptr) * 
                     mxGetN(cell_element_ptr)) + 1;

         /* Allocate enough memory to hold the converted string. */ 
           buf = mxCalloc(buflen, sizeof(char));
           if (buf == NULL)
             mexErrMsgTxt("Not enough heap space to hold string");
           else {
             /* Copy the string data into buf. */
             status = mxGetString(cell_element_ptr, buf, buflen); 

             /* Manipulate the string. */
   ...
            }
      }
   }
}

In MATLAB, create a 2-by-2 cell mxArray named A:

>> A(1,1) = {[1 4 3; 0 5 8; 7 2 9]};
>> A(1,2) = {'Marilyn'};
>> A(2,1) = {3+7i};
>> A(2,2) = {-pi:pi/10:pi}

Passing A as an argument to OneTwo

>> OneTwo(A)

causes OneTwo to convert the contents of cell (1,2) to the C string Marilyn. For an additional example, see mxgetcell.c in the mx subdirectory of the examples directory.