MATLAB Application Program Interface Reference

Create an unpopulated N-dimensional string mxArray

#include "matrix.h"
mxArray *mxCreateCharArray(int ndim, const int *dims);

Arguments

ndim

The desired number of dimensions in the string mxArray. You must specify a positive number. If you specify 0, 1, or 2, mxCreateCharArray creates a two-dimensional mxArray.

dims

The dimensions array. Each element in the dimensions array contains the size of the array in that dimension. For example, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. The dims array must have at least ndim elements.

Returns

A pointer to the created string mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCharArray returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Insufficient free heap space is the only reason for mxCreateCharArray to be unsuccessful.

Description

Call mxCreateCharArray to create an unpopulated N-dimensional string mxArray.

Examples

Call mxCreateCharArray to create a 3-by-80-by-2 string mxArray. Then, populate the string mxArray based on the values in Shake and Twain.

#define ROWS 3
#define COLS 80
#define PAGES 2
 int ndim = 3, dims[]={ROWS, COLS, PAGES};
 mxArray  *array_ptr;
 static char  *Shake[ROWS] = {"Hamlet",
                              "The Tempest",
                              "The Twelfth Night"};
 static char  *Twain[ROWS] = {
                     "A Connecticut Yankee in King Arthur's Court",
                     "The Adventures of Huckleberry Finn",
                     "Tom Sawyer"};
 mxChar  *pr, *original_pr;
 char    *ptr_to_seed_data;
 int      c;

 /* Create a 3-Dimensional character mxArray. */ 
   array_ptr = mxCreateCharArray(ndim, dims);
   if (array_ptr == NULL)
     mexErrMsgTxt("Could not create Character mxArray.");
 
 /* Copy Shake into the mxArray one character at a time. */
   original_pr = (mxChar *)mxGetPr(array_ptr);
   for (c=0; c<ROWS; c++)  {
      pr = original_pr + c; 
      ptr_to_seed_data = Shake[c]; 
      while (*ptr_to_seed_data)  {
           *pr = (mxChar)*ptr_to_seed_data;
           pr += ROWS;
           ptr_to_seed_data++;
      }
   }
      
 /* Copy Twain into the mxArray one character at a time. */
   original_pr = (mxChar *)mxGetPr(array_ptr);
   original_pr += (ROWS * COLS); /* move forward one page. */
   for (c=0; c<ROWS; c++)  {
      pr = original_pr + c; 
      ptr_to_seed_data = Twain[c]; 
      while (*ptr_to_seed_data)  {
           *pr = (mxChar)*ptr_to_seed_data;
           pr += ROWS;
           ptr_to_seed_data++;
      }
   }

For an additional example, see mxCreateCharArray.c in the mx subdirectory of the examples directory.