MATLAB^®

mxGetString (C and Fortran) - Copy string `mxArray` to C-style string

C Syntax

#include "matrix.h"
int mxGetString(const mxArray *pm, char *str, mwSize strlen);

Fortran Syntax

integer*4 mxGetString(pm, str, strlen)
mwPointer pm
character*(*) str
mwSize strlen

Arguments

pm: Pointer to a string mxArray; that is, a pointer to an mxArray having the mxCHAR_CLASS class.
str: The starting location into which the string should be written. mxGetString writes the character data into str and then, in C, terminates the string with a NULL character (in the manner of C strings). str can point to either dynamic or static memory.
strlen: Maximum number of characters to read into str. Typically, in C, you set strlen to 1 plus the number of elements in the string mxArray to which pm points. See the mxGetM and mxGetN reference pages to find out how to get the number of elements.

Returns

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

Specifying an mxArray that is not a string mxArray.
Specifying strlen with less than the number of characters needed to store the entire mxArray pointed to by pm. 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 in C or a character array in Fortran. The copied string starts at str and contains no more than strlen-1 characters in C (no more than strlen characters in Fortran). In C, 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.

Multibyte Character Sets

This function is for use only with strings that represent single-byte character sets. For strings that represent multibyte character sets, use the C function mxArrayToString. Fortran users must allocate sufficient space for the return string to avoid possible truncation.

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

C Examples

Examples:

explore.c in the mex subdirectory of the examples directory
mxmalloc.c in the mx subdirectory of the examples directory

mxGetString (C and Fortran) - Copy string mxArray to C-style string