External Interfaces Reference |
Create unpopulated N-dimensional numeric mxArray
Fortran Syntax
integer*4 function mxCreateNumericArray(ndim, dims, classid, ComplexFlag) integer*4 ndim, dims, classid, ComplexFlag
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:
mxCreateDoubleMatrix
are double-precision, floating-point numbers. The data elements in mxCreateNumericArray
could be any numerical type, including different integer precisions.
mxCreateDoubleMatrix
can create two-dimensional arrays only; mxCreateNumericArray
can create arrays of two or more dimensions.
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
C Create 4x4x2 mxArray of REAL*8 data dims / 4, 4, 2 / mxCreateNumericArray(3, dims, + mxClassIDFromClassName('double'), 0)
See Also
mxCreateDoubleMatrix
, mxCreateNumericMatrix
, mxCreateSparse
, mxCreateString
mxCreateFull (Obsolete) | mxCreateNumericMatrix |
© 1994-2005 The MathWorks, Inc.