mxCreateCharArray (External Interfaces Reference)

Create unpopulated N-dimensional character mxArray

Fortran Syntax

integer*4 function mxCreateCharArray(ndim, dims)
integer*4 ndim, dims

Arguments

ndim
The desired number of dimensions in the character 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(1) to 5 and dims(2) to 7 establishes a 5-by-7 character mxArray. The dims array must have at least ndim elements.

Returns

A pointer to the created character mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCharArray returns 0. 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

Use mxCreateCharArray to create an mxArray of characters whose size is defined by ndim and dims. For example, to establish a two-dimensional mxArray of characters having dimensions 12-by-3, set

```
ndim = 2;
dims(1) = 12; dims(2) = 3;
```

The created mxArray is unpopulated; that is, mxCreateCharArray initializes each character to INTEGER*2 0.

Any trailing singleton dimensions specified in the dims argument are automatically removed from the resulting array. For example, if ndim equals 5 and dims equals [4 1 7 1 1], the resulting array is given the dimensions 4-by-1-by-7.

See Also

mxCreateString

mxCreateCellMatrix mxCreateCharMatrixFromStrings