Matrix *mxCreateString(str)
char *str;
int mxGetString(pm,str,strlen) Matrix *pm;
char *str;
int strlen;
integer*4 function mxCreateString(str)
integer*4 function mxGetString(pm,str,strlen)
integer*4 pm, strlen
character*(
*) str
pm
str
strlen
mxCreateString
returns a pointer to a newly allocated string Matrix containing the specified character string. The NULL
terminator is not copied from str
. mxCreateString
returns NULL
only if the memory allocation failed.
mxGetString
copies, converts, and terminates with a NULL
character the string from the Matrix pm
into the character array str
. Storage space for character array str
must be allocated previously.
Only up to strlen
characters are copied, so ordinarily strlen
is set to the dimension of the character array to prevent writing past the end of the array. Check the length of the character string in advance, using mxGetM
and mxGetN
. If the string Matrix contains several rows, they are copied, one column at a time, into one long string array.
C programmers must allocate a character array, str
, of size strlen
. The value of strlen
is equal to the dimension of the array plus 1 to account for the NULL terminator which mxGetString
places at the end of the array to make it a valid C string.
The following C example illustrates how to use mxGetString
and mxGetN
properly.
#include <math.h> #include "mex.h" #ifdef __STDC__ void mexFunction( int nlhs Matrix *Note in particular the lineplhs[],
int nrhs Matrix *prhs[],
) #else mexFunction(nlhs,plhs,nrhs,prhs) int nlhs, nrhs Matrix *plhs[],
*prhs[];
#endif{
char
*p;
int n;
n = mxGetN(prhs[0])+1;
p = mxCalloc(n,sizeof(char));
mxGetString(prhs[0],p,n);
plhs[0] = mxCreateString(p);
mxFree(p);
}
n = mxGetN(prhs[0])+1;Adding 1 to the value of
n
allocates the correct size for strlen
.
mxGetString
returns 0 if the copy is successful, and 1 if the copy has failed because the Matrix
is not a string Matrix
or the length of the string exceeds strlen
.
In the Fortran versions of these routines, str
is a proper Fortran CHARACTER
variable (not a pointer to it) and is not NULL
terminated.
(c) Copyright 1994 by The MathWorks, Inc.