mxCreateString, mxGetString

Purpose

Create string from Matrix and get string Matrix.

C Synopsis

Matrix *mxCreateString(str)
  char *str;
int mxGetString(pm,str,strlen)
  Matrix *pm;
  char *str;
  int strlen;

Fortran Synopsis

integer*4 function mxCreateString(str)
integer*4 function mxGetString(pm,str,strlen)
integer*4 pm, strlen
character*(*) str

Arguments

pm: pointer to Matrix structure
str: pointer to a string or Fortran string
strlen: length of the character array

Description

These routines allow you to copy strings out of Matrices and to create string Matrices.

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 *plhs[],
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);
}

Note in particular the line

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.