Using the C Math Library

Creating MATLAB Character Arrays

Wherever you pass a character string to a MATLAB C Math Library routine, the string must be a MATLAB character string array, not a standard C null-terminated character string. MATLAB represents characters in 16-bit, Unicode format.

Using Explicit Character Array Creation Routines

The easiest way to create a MATLAB character string is with the MATLAB API routine mxCreateString(). You pass this routine a standard C character string as an argument, delimited by double quotation marks. (In the MATLAB interpreted environment, strings are delimited by single quotation marks.)

mxArray *A = NULL;

mlfAssign(&A, mxCreateString("my string"));

mlfPrintMatrix(A);

mxDestroyArray(A);

This code produces the following output.

my string

Converting Numeric Arrays to Character Arrays

To convert a numeric array into a character array, use the mlfChar() routine. The following code creates an array containing the ASCII codes for each character in "my string" and then call mlfChar() to convert this numeric array into a MATLAB character array.

mxArray *i;
static double ASCII_codes[] = {109,121,32,115, \
                               116,114,105,110,103 };

mlfAssign(&i, mlfDoubleMatrix(1, 9, ASCII_codes, NULL));

mlfPrintMatrix(mlfChar(i,NULL));

mxDestroyArray(A);

This code produces the following output.

my string

To convert this character array back into its underlying numeric representation in double precision format, use the mlfDouble() routine.

Creating Multidimensional Arrays of Strings

You can create a multidimensional array of MATLAB character strings; however, each string must have the same length. The MATLAB C Math Library routines that create arrays of character strings pad the strings with blanks to make them all a uniform length.

Note    To create a multidimensional character array without padding, use cell arrays. For more information, see Cell Arrays.

To illustrate, the following code fragment creates a two-dimensional array character from two strings of different lengths.

mxArray *A = NULL;
mxArray *D1 = NULL;
mxArray *D2 = NULL;

/* create array of strings */
mlfAssign(&A, mlfChar(mxCreateString("my string"),
                      mxCreateString("my dog"),
                      NULL));

mlfPrintMatrix(A);

/* Get the size of each dimension of the array of strings */
mlfSize(mlfVarargout(&D1,&D2,NULL),A,NULL);

/* Print out the size of each dimension */
mlfFprintf(mlfScalar(1),
           mxCreateString("Resulting array is %d-by-%d.\n"),
           D1,
           D2,
           NULL);

mxDestroyArray(A);
mxDestroyArray(D1);
mxDestroyArray(D2);

As the following output illustrates, mlfChar() creates an 2-by-9 character array. This indicates that it added three blanks characters to the string "my dog" to make it the same length as "my string" .

my string
my dog

Resulting array is 2-by-9.

You can also use the mlfStrcat(), mlfStrvcat() and mlfStr2mat() routines to group strings into a multidimensional character array. For more information about these routines, see the online MATLAB C Math Library Reference.

Character Arrays

Accessing Individual Strings in an Array of Strings