mxGetString (C and Fortran)

mxChar array to C-style string or Fortran character array

C Syntax

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

Fortran Syntax

#include "fintrf.h"
integer*4 mxGetString(pm, str, strlen)
mwPointer pm
character*(*) str
mwSize strlen

Arguments

pm

Pointer to an mxChar array.

str

Starting location. 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

Size in bytes of destination buffer pointed to by str. Typically, in C, you set strlen to 1 plus the number of elements in the mxArray to which pm points. To get the number of elements, use mxGetM or mxGetN.

Do not use with Multibyte Encoded Characters.

Returns

0 on success or if strlen == 0, and 1 on failure. Possible reasons for failure include:

• mxArray is not an mxChar array.

• strlen is not large enough to store the entire mxArray. If so, then the function returns 1 and truncates the string.

Description

Call mxGetString to copy the character data of an mxArray into a C-style string in C or a character array in Fortran. The copied data 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 array contains multiple rows, then the function copies them into a single array, one column at a time.

Multibyte Encoded Characters

Use this function only with characters represented in single-byte encoding schemes. For characters represented in multibyte encoding schemes, use the C function mxArrayToString. Fortran applications must allocate sufficient space for the return string to avoid possible truncation.

Examples

To open an example, type:

edit([fullfile(matlabroot,"extern","examples","mx","filename")]);

where filename is:

• mxmalloc.c

To open an example, type:

edit([fullfile(matlabroot,"extern","examples","mex","filename")]);

where filename is:

• explore.c

To open an example, type:

edit([fullfile(matlabroot,"extern","examples","refbook","filename")]);

where filename is:

• revord.F