External Interfaces Reference Previous page   Next Page
mxCreateNumericArray

Create unpopulated N-dimensional numeric mxArray

Fortran Syntax

Arguments

ndim
   Number of dimensions. If you specify a value for ndim that is less than 2, mxCreateNumericArray automatically sets the number of dimensions to 2.

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 mxArray. In most cases, there should be ndim elements in the dims array.

classid
   A numerical identifier that represents a particular MATLAB class. Use the function, mxClassIDFromClassName, to derive the classid value from a class name character array.

The classid tells MATLAB how you want the numerical array data to be represented in memory. For example, specifying the int32 class causes each piece of numerical data in the mxArray to be represented as a 32-bit signed integer.

mxCreateNumericArray accepts any of the MATLAB signed numeric classes, shown to the left in the table below.

ComplexFlag
   If the data you plan to put into the mxArray has no imaginary components, specify 0. If the data will have some imaginary components, specify 1.

Returns

A pointer to the created mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateNumericArray returns 0. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. mxCreateNumericArray is unsuccessful when there is not enough free heap space to create the mxArray.

Description

Call mxCreateNumericArray to create an N-dimensional mxArray in which all data elements have the numeric data type specified by classid. After creating the mxArray, mxCreateNumericArray initializes all its real data elements to 0. If ComplexFlag is set to 1, mxCreateNumericArray also initializes all its imaginary data elements to 0.

The following table shows the Fortran data types that are equivalent to MATLAB classes. Use these as shown in the example below.

MATLAB Class Name
Fortran Type
int8
INTEGER*1
int16
INTEGER*2
int32
INTEGER*4
single
REAL*4
double
REAL*8
single, with imaginary components
COMPLEX*8
double, with imaginary components
COMPLEX*16

mxCreateNumericArray differs from mxCreateDoubleMatrix in two important respects:

mxCreateNumericArray allocates dynamic memory to store the created mxArray. When you finish with the created mxArray, call mxDestroyArray to deallocate its memory.

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.

Example

To create a 4-by-4-by-2 array of REAL*8 elements having no imaginary components, use

See Also

mxCreateDoubleMatrix, mxCreateNumericMatrix, mxCreateSparse, mxCreateString


Previous page  mxCreateFull (Obsolete) mxCreateNumericMatrix Next page

© 1994-2005 The MathWorks, Inc.