mxGetString (MATLAB Application Program Interface)

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

C Syntax

#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

See revord.c in the refbook subdirectory of the examples directory.

For additional examples, see explore.c in the mex subdirectory of the examples directory; see mxmalloc.c and mxsetallocfcns.c in the mx subdirectory of the examples directory.