Learn more about MATLAB

mxCreateNumericArray (C and Fortran) - Create unpopulated N-D numeric mxArray

C Syntax

#include "matrix.h"
mxArray *mxCreateNumericArray(mwSize ndim, const mwSize *dims, 
         mxClassID classid, mxComplexity ComplexFlag);

Fortran Syntax

mwPointer mxCreateNumericArray(ndim, dims, classid, 
  ComplexFlag)
mwSize ndim, dims
integer*4 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

Dimensions array. Each element in the dimensions array contains the size of the array in that dimension. For example, in C, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. In Fortran, 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

Identifier for the class of the array, which determines the way the numerical data is represented in memory. For example, specifying mxINT16_CLASS in C causes each piece of numerical data in the mxArray to be represented as a 16-bit signed integer. In Fortran, use the function mxClassIDFromClassName to derive the classid value from a MATLAB class name. See the Description section for more information.

ComplexFlag

If the data you plan to put into the mxArray has no imaginary components, specify mxREAL in C (0 in Fortran). If the data has some imaginary components, specify mxCOMPLEX in C (1 in Fortran).

Returns

Pointer to the created mxArray, if successful. If unsuccessful in a stand alone (non-MEX-file) application, mxCreateNumericArray returns NULL in C (0 in Fortran). 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 equals mxCOMPLEX in C (1 in Fortran), mxCreateNumericArray also initializes all its imaginary data elements to 0. mxCreateNumericArray differs from mxCreateDoubleMatrix in two important respects:

• All data elements in 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.

The following table shows the C classid values and the Fortran data types that are equivalent to MATLAB classes.

MATLAB Class Name	C classid Value	Fortran Type
int8	mxINT8_CLASS	BYTE
uint8	mxUINT8_CLASS
int16	mxINT16_CLASS	INTEGER*2
uint16	mxUINT16_CLASS
int32	mxINT32_CLASS	INTEGER*4
uint32	mxUINT32_CLASS
int64	mxINT64_CLASS	INTEGER*8
uint64	mxUINT64_CLASS
single	mxSINGLE_CLASS	REAL*4
double	mxDOUBLE_CLASS	REAL*8
single, with imaginary components	mxSINGLE_CLASS	COMPLEX*8
double, with imaginary components	mxDOUBLE_CLASS	COMPLEX*16

C Examples

See phonebook.c and doubleelement.c in the matlabroot/extern/examples/refbook folder . For an additional example, see mxisfinite.c in the matlabroot/extern/examples/mx folder .

Fortran Examples

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

mxClassId, mxClassIdFromClassName, mxComplexity, mxCreateNumericMatrix

mxCreateLogicalScalar (C)

mxCreateNumericMatrix (C and Fortran)

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS