MATLAB Application Program Interface Reference | Help Desk |
mxCreateCharMatrixFromStrings
Create a populated 2-dimensional stringmxArray
#include "matrix.h" mxArray *mxCreateCharMatrixFromStrings(int m, const char **str);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
.
A pointer to a list of strings. The str
array must contain at least m
strings.
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.
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
.
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
mxCreateCharMatrixFromStrings.c
in the mx
subdirectory of the examples
directory.
mxCreateCharArray
, mxCreateString
, mxGetString