C Matrix API String Handling Functions

How MATLAB Represents Strings in MEX Files

In C/C++ MEX functions built with the C Matrix API, a MATLAB^® character vector is an mxArray of type mxChar, using a locale-neutral data representation (Unicode^® encoding). MATLAB represents C-style strings as type char, and uses the character encoding scheme specified by the user locale setting.

The following C Matrix API functions provide string handling functions to help you work with both mxArrays and C-style strings.

mxCreateString — Creates a mxChar mxArray initialized to the input string.
mxArrayToString — Copies a mxChar mxArray into a C-style string. Supports multibyte encoded characters.
mxGetString — Copies a mxChar mxArray into a C-style string. Best used with single-byte encoded characters. Supports multibyte encoded characters when you calculate string buffer size.
mxGetChars — Returns a pointer to the first mxChar element in the mxArray.

Consider the following topics when choosing a string handling function.

Character Encoding and Multibyte Encoding Schemes

MATLAB supports the character encoding scheme specified by the user locale setting. When an MX Library function converts mxChar data to a C char type, MATLAB also converts the character to the user default encoding.

If you use a multibyte encoding scheme, use the mxArrayToString function.

The mxGetChars function provides a pointer to the mxChar array; it does not change the character encoding.

You can also use the mxGetString function with multibyte encoding schemes. mxGetString converts the mxChar data to your user default encoding, and copies the converted characters to the destination buffer. However, you must calculate the size of the destination buffer. For single-byte encoding, the size of the buffer is the number of characters, plus 1 for the null terminator. For multibyte encoding, the size of a character is one or more bytes. Some options for calculating the buffer size are to overestimate the amount (calculating the number of characters times the maximum number of bytes used by the encoding scheme), analyze the string to determine the precise size used by each character, or utilize 3rd-party string buffer libraries. After this calculation, add 1 for the null terminator.

Converting MATLAB Character Vector to C-Style String

When you pass a character array to a MEX function, it is an mxArray of type mxChar. If you call a C function to manipulate the string, first convert the data to a C type char using the mxArrayToString or mxGetString functions.

Converting C-Style String to MATLAB Character Vector

If your MEX file creates a C string and returns the data to MATLAB, use the mxCreateString function to copy the C string into an mxChar array.

Returning Modified Input String

Suppose that your MEX file takes character input, modifies it, and returns the result. Since MEX file input parameters (the prhs array) are read-only, you must define a separate output parameter to handle the modified string.

Memory Management

MathWorks^® recommends that MEX file functions destroy their own temporary arrays and free their own dynamically allocated memory. The function you use to release memory depends on how you use the string buffer and what function you use to create the buffer.

If You Call This Function	Release Memory Using This Function
Any string function listed here	Do not destroy an `mxArray` in a source MEX file when it is: Passed to the MEX file in the right-hand side list `prhs[]`. Returned in the left side list `plhs[]`. Returned by the `mexGetVariablePtr` function. Used to create a structure.
`mxArrayToString`	`mxFree`
`mxGetString`	When using `mxCalloc` / `mxMalloc` / `mxRealloc` to create input argument `buf`, call `mxFree(buf)`.
`mxCreateString`	`mxDestroyArray`
`mxGetChars`	None. Function creates a pointer to an `mxArray` but does not allocate additional memory.