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
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
mxCharmxArray initialized to the input string.
mxArrayToString— Copies a
mxCharmxArray into a C-style string. Supports multibyte encoded characters.
mxGetString— Copies a
mxCharmxArray 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
mxCharelement 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
If you use a multibyte encoding scheme, use the
mxGetChars function provides a pointer
mxChar array; it does not change the
You can also use the
mxGetString function with multibyte
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
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
char using the
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
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
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
None. Function creates a pointer to