MATLAB Application Program Interface Reference

Copy a string mxArray's data into a C-style string

#include "matrix.h"
int mxGetString(const mxArray *array_ptr, char *buf, int buflen);

Arguments

array_ptr

Pointer to a string mxArray; that is, a pointer to an mxArray having the mxCHAR_CLASS class.

buf

The starting location into which the string should be written. mxGetString writes the string data into buf and then terminates the string with a NULL character (in the manner of C strings). Although buf is traditionally stored in dynamic memory, buf could be put into static memory instead.

buflen

Maximum number of characters to read into buf. Typically, you set buflen to 1 plus the number of elements in the string mxArray to which array_ptr points. (See the mxGetM and mxGetN reference pages to find out how to get the number of elements.)

Returns

0 on success, and 1 on failure. Possible reasons for failure include

Specifying an mxArray that is not a string mxArray.
Failing to allocate enough space for buf. You must allocate enough space to hold at least buflen characters.

Description

Call mxGetString to copy the string data of a string mxArray into a C-style string. The copied C-style string starts at buf and contains no more than buflen-1 characters.

If the string array contains several rows, they are copied, one column at a time, into one long string array.

Examples

Use mxGetString to convert the data from a string array into a C string named buf:

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 char *buf;
 int   buflen;
 int   status;

 /* Find out how long the input string array is. */
   buflen = (mxGetM(prhs[0]) * mxGetN(prhs[0])) + 1;

 /* Allocate enough memory to hold the converted string. */ 
   buf = mxCalloc(buflen, sizeof(char));
   if (buf == NULL)
     mexErrMsgTxt("Not enough heap space to hold converted 
string.");

 /* Copy the string data from prhs[0] and place it into buf. */ 
   status = mxGetString(prhs[0], buf, buflen); 
   if (status == 0)
     mexPrintf("The converted string is \n%s.\n", buf);
   else
     mexErrMsgTxt("Could not convert string data.");

 /* Manipulate buf as you would manipulate any C string. */ 
   ...
}

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