# 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.

(c) Copyright 1994 by The MathWorks, Inc.