MATLAB Application Program Interface Reference

Create an unpopulated N-dimensional numeric mxArray

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

Arguments

ndim

Number of dimensions. If you specify a value for ndims 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[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. In most cases, there should be ndim elements in the dims array.

class

The way in which the numerical data is to be represented in memory. For example, specifying mxINT16_CLASS causes each piece of numerical data in the mxArray to be represented as a 16-bit signed integer. You can specify any class except for mxNUMERIC_CLASS, mxSTRUCT_CLASS, mxCELL_CLASS, or mxOBJECT_CLASS.

ComplexFlag

Specify either mxREAL or mxCOMPLEX. If the data you plan to put into the mxArray has no imaginary components, specify mxREAL. If the data will have some imaginary components, specify mxCOMPLEX.

Returns

A pointer to the created mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateNumericArray returns NULL. 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 class. After creating the mxArray, mxCreateNumericArray initializes all its real data elements to 0. If ComplexFlag equals mxCOMPLEX, 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.

Examples

Call mxCreateNumericArray to create a 2-by-3-by-2 mxArray of unsigned 8-bit integers. Then, call a combination of functions to populate the mxArray:

#define  FIRST_DIM  2
#define  SECOND_DIM 3
#define  THIRD_DIM  2
#define  TOTAL_ELEMENTS (FIRST_DIM * SECOND_DIM * THIRD_DIM)
 int      ndim = 3, dims[3] = {FIRST_DIM, SECOND_DIM, THIRD_DIM};
 unsigned char  real_data[] = {9, 7, 5, 2, 6, 3, 4, 8, 2, 1, 10, 5};
 unsigned char *start_of_pr;
 unsigned char *start_of_pi;
 mxArray       *array_ptr;
 size_t   bytes_to_copy;

 /* Create a 2-by-3-by-2 array of unsigned 8-bit integers. */ 
   array_ptr = mxCreateNumericArray(ndim, dims, mxUINT8_CLASS, 
                                     mxREAL);
   if (array_ptr == NULL)
     mexErrMsgTxt("Could not create mxArray.\n");

 /* Populate the real part of the created array. */ 
   start_of_pr = (unsigned char *)mxGetPr(array_ptr);
   bytes_to_copy = TOTAL_ELEMENTS * mxGetElementSize(array_ptr);
   memcpy(start_of_pr, real_data, bytes_to_copy);

 /* Populate the imaginary part of the created array. */ 
   start_of_pi = (unsigned char *)mxGetPi(array_ptr);
   memcpy(start_of_pi, real_data, bytes_to_copy);

For an additional example, see mxCreateNumericArray.c in the mx subdirectory of the examples directory.