MATLAB Application Program Interface Reference | Help Desk |
mxCreateNumericArray
Create an unpopulated N-dimensional numericmxArray
#include "matrix.h" mxArray *mxCreateNumericArray(int ndim, const int *dims, mxClassID class, mxComplexity ComplexFlag);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.
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.
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
.
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
.
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
.
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
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.
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.
mxCreateDoubleMatrix
, mxCreateSparse
, mxCreateString
, mxComplexity