mxCreateCharMatrixFromStrings (MATLAB Application Program Interface)

Create a populated 2-dimensional string mxArray

#include "matrix.h"
mxArray *mxCreateCharMatrixFromStrings(int m, const char **str);

Arguments

m
The desired number of rows in the created string mxArray. The value you specify for m should equal the number of strings in str.

str
A pointer to a list of strings. The str array must contain at least m strings.

Returns

A pointer to the created string mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCharMatrixFromStrings returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Insufficient free heap space is the primary reason for mxCreateCharArray to be unsuccessful. Another possible reason for failure is that str contains fewer than m strings.

Description

Use mxCreateCharMatrixFromStrings to create a two-dimensional string mxArray, where each row is initialized to a string from str. The created mxArray has dimensions m-by-max, where max is the length of the longest string in str.

Note that string mxArrays represent their data elements as mxChar rather than as char.

Examples

Create a 3-by-22 string mxArray initialized to all the three substrings of Shake:

#include "mex.h"
void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
/* BEGIN */
#define ROWS 3
 static const char  *Shake[ROWS] = {"To be or not to be.",
                                    "Aye.  There's the rub.",
                                    "Out, out, damn spot."};
 mxArray    *array_ptr;
/* END */
 int rows, columns;
/* BEGIN */
/* Create a 2-Dimensional string mxArray initialized to Shake. */
   array_ptr = mxCreateCharMatrixFromStrings(ROWS, Shake);
/*END*/
   mxSetName(array_ptr, "s");

   rows = mxGetM(array_ptr);
   columns = mxGetN(array_ptr);
   mexPrintf("Rows = %d; Columns = %d\n", rows, columns);
 
/* Place the string array in the MATLAB workspace, then invoke
   a MATLAB string manipulation function on it. */ 
   mexPutArray(array_ptr, "caller");
   mexEvalString("s2 = upper(s)");

/*BEGIN */

/* PONGO */

 /* When finished with the string array, free its memory. */
   mxDestroyArray(array_ptr);
/* END */
}

For an additional example, see mxcreatecharmatrix.c in the mx subdirectory of the examples directory.