MATLAB Application Program Interface Reference

Create a 1-by-n string mxArray initialized to the specified string

#include "matrix.h"
mxArray *mxCreateString(const char *str);

Arguments

str

The C string that is to serve as the mxArray's initial data.

Returns

A pointer to the created string mxArray, if successful; otherwise, returns NULL. The most likely cause of failure is insufficient free heap space.

Description

Use mxCreateString to create a string mxArray initialized to str. Many MATLAB functions (for example, strcmp and upper) require string array inputs.

Free the string mxArray when you are finished using it. To free a string mxArray, call mxDestroyArray.

Examples

Create a string mxArray named s containing the value of string idiom:

mxArray    *array_ptr;
 const char  idiom[] = "Everyone loves MATLAB.";
 
 /* Create a string array. */
   array_ptr = mxCreateString(idiom); 
 
 /* Name the string array "s". */ 
   mxSetName(array_ptr, "s");
 
 /* Place the string array in the MATLAB workspace, then invoke
    a MATLAB string manipulation function on it. */ 
   mexPutArray(array_ptr, "caller");
   mexEvalString("us = upper(s)");

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

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