mxGetString (MATLAB Application Program Interface)

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 character data into buf and then terminates the string with a NULL character (in the manner of C strings). buf can either point to dynamic or static memory.

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.)

Note: Users of multibyte character sets should be aware that MATLAB packs multibyte characters into an mxChar (16-bit unsigned integer). When allocating space for the return string, to avoid possible truncation you should set

buflen = (mxGetM(prhs[0] * mxGetN(prhs[0]) * sizeof(mxChar)) + 1

Returns

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

Specifying an mxArray that is not a string mxArray.
Specifying buflen with less than the number of characters needed to store the entire mxArray pointed to by array_ptr. If this is the case, 1 is returned and the string is truncated.

Description

Call mxGetString to copy the character 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. The C-style string is always terminated with a NULL character.

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. Note: Users of 
multibyte character sets should uncomment and use the second 
buflen statement that follows and should comment out the first 
buflen statement that follows. */

buflen = (mxGetM(prhs[0]) * mxGetN(prhs[0])) + 1;
/* buflen = (mxGetM(prhs[0]*mxGetN(prhs[0])*sizeof(mxChar))+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.