C Matrix API

Write C/C++ programs that work with the MATLAB® mxArray data structure

To write C programs that work with MATLAB R2017b or earlier, use functions in the C Matrix API. These functions work with the mxArray data structure and are used to build C MEX functions or C engine applications.

Note

MathWorks recommends that whenever possible, choose C++ over C applications. For more information, see Calling MATLAB from C++ or C++ Libraries to directly call C++ library functionality from MATLAB.

There are two versions of the C Matrix API.

For examples using these library functions, see:

Caution

The C Matrix API is not compatible with the MATLAB Data API, which supports modern C++ features. You cannot use C Matrix API functions with functions in the C++ MEX Applications or MATLAB Engine API for C++.

C Data Types

mxArrayC type for MATLAB array
mwSizeType for size values
mwIndexType for index values
mwSignedIndexSigned integer type for size values
mxCharType for string array
mxLogicalType for logical array
mxComplexityFlag specifying whether array has imaginary components

mxArray Attributes

mxIsNumericDetermine whether array is numeric
mxIsComplexDetermine whether data is complex
mxGetNumberOfDimensionsNumber of dimensions in array
mxGetElementSizeNumber of bytes required to store each data element
mxGetDimensionsPointer to dimensions array
mxSetDimensionsModify number of dimensions and size of each dimension
mxGetNumberOfElementsNumber of elements in numeric array
mxCalcSingleSubscriptOffset from first element to desired element
mxGetMNumber of rows in array
mxSetMSet number of rows in array
mxGetNNumber of columns in array
mxSetNSet number of columns in array
mxIsEmptyDetermine whether array is empty
mxIsFromGlobalWSDetermine whether array was copied from MATLAB global workspace

Create, Query, and Access Data Types

expand all

mxCreateDoubleMatrix2-D, double-precision, floating-point array
mxCreateDoubleScalarScalar, double-precision array initialized to specified value
mxCreateNumericMatrix2-D numeric matrix
mxCreateNumericArrayN-D numeric array
mxCreateUninitNumericMatrixUninitialized 2-D numeric matrix
mxCreateUninitNumericArrayUninitialized N-D numeric array
mxIsScalarDetermine whether array is scalar array
mxGetScalarReal component of first data element in array
mxIsDoubleDetermine whether mxArray represents data as double-precision, floating-point numbers
mxGetDoublesReal data elements in mxDOUBLE_CLASS array
mxSetDoublesSet real data elements in mxDOUBLE_CLASS array
mxIsSingleDetermine whether array represents data as single-precision, floating-point numbers
mxGetSinglesReal data elements in mxSINGLE_CLASS array
mxSetSinglesSet real data elements in mxSINGLE_CLASS array
mxGetPr(Not recommended) Real data elements in mxDOUBLE_CLASS array
mxSetPr(Not recommended) Set real data elements in mxDOUBLE_CLASS array
mxIsInt8Determine whether array represents data as signed 8-bit integers
mxGetInt8sReal data elements in mxINT8_CLASS array
mxSetInt8sSet real data elements in mxINT8_CLASS array
mxIsUint8Determine whether array represents data as unsigned 8-bit integers
mxGetUint8sReal data elements in mxUINT8_CLASS array
mxSetUint8sSet real data elements in mxUINT8_CLASS array
mxIsInt16Determine whether array represents data as signed 16-bit integers
mxGetInt16sReal data elements in mxINT16_CLASS array
mxSetInt16sSet real data elements in mxINT16_CLASS array
mxIsUint16Determine whether array represents data as unsigned 16-bit integers
mxGetUint16sReal data elements in mxUINT16_CLASS array
mxSetUint16sSet real data elements in mxUINT16_CLASS array
mxIsInt32Determine whether array represents data as signed 32-bit integers
mxGetInt32sReal data elements in mxINT32_CLASS array
mxSetInt32sSet real data elements in mxINT32_CLASS array
mxIsUint32Determine whether array represents data as unsigned 32-bit integers
mxGetUint32sReal data elements in mxUINT32_CLASS array
mxSetUint32sSet real data elements in mxUINT32_CLASS array
mxIsInt64Determine whether array represents data as signed 64-bit integers
mxGetInt64sReal data elements in mxINT64_CLASS array
mxSetInt64sSet data elements in mxINT64_CLASS array
mxIsUint64Determine whether array represents data as unsigned 64-bit integers
mxGetUint64sReal data elements in mxUINT64_CLASS array
mxSetUint64sSet real data elements in mxUINT64_CLASS array
mxGetComplexDoublesComplex data elements in mxDOUBLE_CLASS array
mxSetComplexDoublesSet complex data elements in mxDOUBLE_CLASS array
mxGetComplexSinglesComplex data elements in mxSINGLE_CLASS array
mxSetComplexSinglesSet complex data elements in mxSINGLE_CLASS array
mxGetImagDataImaginary data elements in numeric mxArray
mxSetImagDataSet imaginary data elements in numeric mxArray
mxGetPi(Not recommended) Imaginary data elements in mxDOUBLE_CLASS array
mxSetPi(Not recommended) Set imaginary data elements in mxDOUBLE_CLASS array
mxGetComplexInt8sComplex data elements in mxINT8_CLASS array
mxSetComplexInt8sSet complex data elements in mxINT8_CLASS array
mxGetComplexUint8sComplex data elements in mxUINT8_CLASS array
mxSetComplexUint8sSet complex data elements in mxUINT8_CLASS array
mxGetComplexInt16sComplex data elements in mxINT16_CLASS array
mxSetComplexInt16sSet complex data elements in mxINT16_CLASS array
mxGetComplexUint16sComplex data elements in mxUINT16_CLASS array
mxSetComplexUint16sSet complex data elements in mxUINT16_CLASS array
mxGetComplexInt32sComplex data elements in mxINT32_CLASS array
mxSetComplexInt32sSet complex data elements in mxINT32_CLASS array
mxGetComplexUint32sComplex data elements in mxUINT32_CLASS array
mxSetComplexUint32sSet complex data elements in mxUINT32_CLASS array
mxGetComplexInt64sComplex data elements in mxINT64_CLASS array
mxSetComplexInt64sSet complex data elements in mxINT64_CLASS array
mxGetComplexUint64sComplex data elements in mxUINT64_CLASS array
mxSetComplexUint64sSet complex data elements in mxUINT64_CLASS array
mxGetPi(Not recommended) Imaginary data elements in mxDOUBLE_CLASS array
mxSetPi(Not recommended) Set imaginary data elements in mxDOUBLE_CLASS array
mxCreateSparse2-D sparse array
mxCreateSparseLogicalMatrix2-D, sparse, logical array
mxIsSparseDetermine whether input is sparse array
mxGetNzmaxNumber of elements in IR, PR, and PI arrays
mxSetNzmaxSet storage space for nonzero elements
mxGetIrSparse matrix IR array
mxSetIrIR array of sparse array
mxGetJcSparse matrix JC array
mxSetJcJC array of sparse array
mxGetDataData elements in nonnumeric mxArray
mxSetDataSet pointer to data elements in nonnumeric mxArray
mxCreateString1-N array initialized to specified string
mxCreateCharMatrixFromStrings2-D mxChar array initialized to specified value
mxCreateCharArrayN-D mxChar array
mxIsCharDetermine whether input is mxChar array
mxGetCharsPointer to character array data
mxIsLogicalDetermine whether array is of type mxLogical
mxIsLogicalScalarDetermine whether scalar array is of type mxLogical
mxIsLogicalScalarTrueDetermine whether scalar array of type mxLogical is true
mxClassIDEnumerated value identifying class of array
mxCreateLogicalArrayN-D logical array
mxCreateLogicalMatrix2-D logical array
mxCreateLogicalScalarScalar, logical array
mxGetLogicalsPointer to logical array data
mxIsClassDetermine whether array is object of specified class
mxGetClassIDClass of array
mxGetClassNameClass of array as string
mxSetClassNameStructure array to MATLAB object array
mxGetPropertyValue of public property of MATLAB object
mxSetPropertySet value of public property of MATLAB object
mxCreateStructMatrix2-D structure array
mxCreateStructArrayN-D structure array
mxIsStructDetermine whether input is structure array
mxGetFieldPointer to field value from structure array, given index and field name
mxSetFieldSet field value in structure array, given index and field name
mxGetNumberOfFieldsNumber of fields in structure array
mxGetFieldNameByNumberPointer to field name from structure array, given field number
mxGetFieldNumberField number from structure array, given field name
mxGetFieldByNumberPointer to field value from structure array, given index and field number
mxSetFieldByNumberSet field value in structure array, given index and field number
mxAddFieldAdd field to structure array
mxRemoveFieldRemove field from structure array
mxCreateCellMatrix2-D cell array
mxCreateCellArrayN-D cell array
mxIsCellDetermine whether input is cell array
mxGetCellPointer to element in cell array
mxSetCellSet contents of cell array

Delete and Duplicate mxArray

mxDestroyArrayFree dynamic memory allocated by MXCREATE* functions
mxDuplicateArrayMake deep copy of array

Convert mxArray

expand all

mxMakeArrayComplexConvert real mxArray to complex, preserving real data
mxMakeArrayRealConvert complex mxArray to real, preserving real data
mxArrayToStringArray to string
mxArrayToUTF8StringArray to string in UTF-8 encoding
mxGetStringmxChar array to C-style string or Fortran character array
mxSetClassNameStructure array to MATLAB object array

Data Memory Management

mxCallocAllocate dynamic memory for array, initialized to 0, using MATLAB memory manager
mxMallocAllocate uninitialized dynamic memory using MATLAB memory manager
mxReallocReallocate dynamic memory using MATLAB memory manager
mxFreeFree dynamic memory allocated by mxCalloc, mxMalloc, mxRealloc, mxArrayToString, or mxArrayToUTF8String functions

Asserts

mxAssertCheck assertion value for debugging purposes
mxAssertSCheck assertion value without printing assertion text

Constants

mxIsInfDetermine whether input is infinite
mxIsFiniteDetermine whether input is finite
mxIsNaNDetermine whether input is NaN (Not-a-Number)

Topics

Pass Strings in C MEX File

This example shows how to pass strings to a MEX function built with the C Matrix API.

Pass Scalar Values in C MEX File

This example shows how to write a MEX file that passes scalar values.

Handle Sparse Arrays in C MEX File

This example shows how to populate a sparse matrix using the C Matrix API.

Handle 8-, 16-, 32-, and 64-Bit Data in C MEX File

This example shows how to use unsigned 16-bit integers in a MEX file using the C Matrix API.

Pass Structures and Cell Arrays in C MEX File

This example shows how to pass structures and cell arrays to MEX files built with the C Matrix API.

Manipulate Multidimensional Numerical Arrays in C MEX Files

You can manipulate multidimensional numerical arrays by using typed data access functions like mxGetDoubles and mxGetComplexDoubles.

Related Information

MATLAB Documentation
Support