C Matrix API

Use the C Matrix API to create C programs that use the mxArray type to represent MATLAB data

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

Whenever possible, choose C++ over C applications.

There are two versions of the C Matrix API.

The interleaved complex API contains the C Matrix API functionality as of MATLAB R2018a. For more information, see MATLAB Support for Interleaved Complex API in MEX Functions.
The separate complex API contains the C Matrix API functionality as of MATLAB R2017b.

For examples using these library functions, see:

Tables of MEX Function Source Code Examples
Table of MAT-File Source Code Files
See individual functions for example information. For example, see mxIsChar.

Caution

The C Matrix API is not compatible with the MATLAB Data API for C++, which supports modern C++ features. You cannot use C Matrix API functions with functions in the MATLAB APIs described in Write C++ Functions Callable from MATLAB (MEX Files) or Call MATLAB from C++.

C Data Types

`mxArray`	C type for MATLAB array
`mwSize`	C type for mxArray size values
`mwIndex`	C type for mxArray index values
`mwSignedIndex`	Signed integer C type for mxArray size values
`mxChar`	Type for string array
`mxLogical`	Type for logical array
`mxComplexity`	Flag specifying whether array has imaginary components

mxArray Attributes

`mxIsNumeric`	Determine whether mxArray is numeric
`mxIsComplex`	Determine whether data is complex
`mxGetNumberOfDimensions`	Number of dimensions in mxArray
`mxGetElementSize`	Number of bytes required to store each data element
`mxGetDimensions`	Pointer to dimensions array
`mxSetDimensions`	Modify number of dimensions and size of each dimension
`mxGetNumberOfElements`	Number of elements in numeric mxArray
`mxCalcSingleSubscript`	Offset from first element to desired element
`mxGetM`	Number of rows in mxArray
`mxSetM`	Set number of rows in mxArray
`mxGetN`	Number of columns in mxArray
`mxSetN`	Set number of columns in mxArray
`mxIsEmpty`	Determine whether mxArray is empty
`mxIsFromGlobalWS`	Determine whether mxArray was copied from MATLAB global workspace

Create, Query, and Access Data Types

expand all

Numeric Types

`mxCreateDoubleMatrix`	2-D, double-precision, floating-point array
`mxCreateDoubleScalar`	Scalar, double-precision array initialized to specified value
`mxCreateNumericMatrix`	2-D numeric matrix
`mxCreateNumericArray`	N-D numeric array
`mxCreateUninitNumericMatrix`	Uninitialized 2-D numeric matrix
`mxCreateUninitNumericArray`	Uninitialized N-D numeric array

Noncomplex Float

`mxIsScalar`	Determine whether array is scalar array
`mxGetScalar`	Real component of first data element in array
`mxIsDouble`	Determine whether mxArray represents data as double-precision, floating-point numbers
`mxGetDoubles`	Real data elements in `mxDOUBLE_CLASS` array
`mxSetDoubles`	Set real data elements in `mxDOUBLE_CLASS` array
`mxIsSingle`	Determine whether mxArray represents data as single-precision, floating-point numbers
`mxGetSingles`	Real data elements in `mxSINGLE_CLASS` array
`mxSetSingles`	Set 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

Noncomplex Integer

`mxIsInt8`	Determine whether mxArray represents data as signed 8-bit integers
`mxGetInt8s`	Real data elements in `mxINT8_CLASS` array
`mxSetInt8s`	Set real data elements in `mxINT8_CLASS` array
`mxIsUint8`	Determine whether mxArray represents data as unsigned 8-bit integers
`mxGetUint8s`	Real data elements in `mxUINT8_CLASS` array
`mxSetUint8s`	Set real data elements in `mxUINT8_CLASS` array
`mxIsInt16`	Determine whether mxArray represents data as signed 16-bit integers
`mxGetInt16s`	Real data elements in `mxINT16_CLASS` array
`mxSetInt16s`	Set real data elements in `mxINT16_CLASS` array
`mxIsUint16`	Determine whether mxArray represents data as unsigned 16-bit integers
`mxGetUint16s`	Real data elements in `mxUINT16_CLASS` array
`mxSetUint16s`	Set real data elements in `mxUINT16_CLASS` array
`mxIsInt32`	Determine whether mxArray represents data as signed 32-bit integers
`mxGetInt32s`	Real data elements in `mxINT32_CLASS` array
`mxSetInt32s`	Set real data elements in `mxINT32_CLASS` array
`mxIsUint32`	Determine whether mxArray represents data as unsigned 32-bit integers
`mxGetUint32s`	Real data elements in `mxUINT32_CLASS` array
`mxSetUint32s`	Set real data elements in `mxUINT32_CLASS` array
`mxIsInt64`	Determine whether mxArray represents data as signed 64-bit integers
`mxGetInt64s`	Real data elements in `mxINT64_CLASS` array
`mxSetInt64s`	Set data elements in `mxINT64_CLASS` array
`mxIsUint64`	Determine whether mxArray represents data as unsigned 64-bit integers
`mxGetUint64s`	Real data elements in `mxUINT64_CLASS` array
`mxSetUint64s`	Set real data elements in `mxUINT64_CLASS` array

Complex Float

`mxGetComplexDoubles`	Complex data elements in `mxDOUBLE_CLASS` array
`mxSetComplexDoubles`	Set complex data elements in `mxDOUBLE_CLASS` array
`mxGetComplexSingles`	Complex data elements in `mxSINGLE_CLASS` array
`mxSetComplexSingles`	Set complex data elements in `mxSINGLE_CLASS` array
`mxGetImagData`	Imaginary data elements in numeric `mxArray`
`mxSetImagData`	Set 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

Complex Integer

`mxGetComplexInt8s`	Complex data elements in `mxINT8_CLASS` array
`mxSetComplexInt8s`	Set complex data elements in `mxINT8_CLASS` array
`mxGetComplexUint8s`	Complex data elements in `mxUINT8_CLASS` array
`mxSetComplexUint8s`	Set complex data elements in `mxUINT8_CLASS` array
`mxGetComplexInt16s`	Complex data elements in `mxINT16_CLASS` array
`mxSetComplexInt16s`	Set complex data elements in `mxINT16_CLASS` array
`mxGetComplexUint16s`	Complex data elements in `mxUINT16_CLASS` array
`mxSetComplexUint16s`	Set complex data elements in `mxUINT16_CLASS` array
`mxGetComplexInt32s`	Complex data elements in `mxINT32_CLASS` array
`mxSetComplexInt32s`	Set complex data elements in `mxINT32_CLASS` array
`mxGetComplexUint32s`	Complex data elements in `mxUINT32_CLASS` array
`mxSetComplexUint32s`	Set complex data elements in `mxUINT32_CLASS` array
`mxGetComplexInt64s`	Complex data elements in `mxINT64_CLASS` array
`mxSetComplexInt64s`	Set complex data elements in `mxINT64_CLASS` array
`mxGetComplexUint64s`	Complex data elements in `mxUINT64_CLASS` array
`mxSetComplexUint64s`	Set 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

Sparse

`mxCreateSparse`	2-D sparse array
`mxCreateSparseLogicalMatrix`	2-D, sparse, logical array
`mxIsSparse`	Determine whether input is sparse mxArray
`mxGetNzmax`	Number of elements in IR, PR, and PI arrays
`mxSetNzmax`	Set storage space for nonzero elements
`mxGetIr`	Sparse matrix IR array
`mxSetIr`	IR array of sparse array
`mxGetJc`	Sparse matrix JC array
`mxSetJc`	JC array of sparse array

Nonnumeric Types

`mxGetData`	Data elements in nonnumeric `mxArray`
`mxSetData`	Set pointer to data elements in nonnumeric `mxArray`

Character

`mxCreateString`	1-D array initialized to specified string
`mxCreateCharMatrixFromStrings`	2-D `mxChar` array initialized to specified value
`mxCreateCharArray`	N-D `mxChar` array
`mxIsChar`	Determine whether input is `mxChar` array
`mxGetChars`	Pointer to character array data

Logical

`mxIsLogical`	Determine whether mxArray is of type `mxLogical`
`mxIsLogicalScalar`	Determine whether scalar array is of type mxLogical
`mxIsLogicalScalarTrue`	Determine whether scalar array of type mxLogical is true
`mxClassID`	Enumerated value identifying class of array
`mxCreateLogicalArray`	N-D logical array
`mxCreateLogicalMatrix`	2-D logical array
`mxCreateLogicalScalar`	Scalar, logical array
`mxGetLogicals`	Pointer to logical array data

Object

`mxIsClass`	Determine whether mxArray is object of specified class
`mxGetClassID`	Class of mxArray
`mxGetClassName`	Class of mxArray as string
`mxSetClassName`	Structure array to MATLAB object array
`mxGetProperty`	Value of public property of MATLAB object
`mxSetProperty`	Set value of public property of MATLAB object

Structure

`mxCreateStructMatrix`	2-D structure array
`mxCreateStructArray`	N-D structure array
`mxIsStruct`	Determine whether mxArray is structure
`mxGetField`	Pointer to field value from structure array, given index and field name
`mxSetField`	Set field value in structure array, given index and field name
`mxGetNumberOfFields`	Number of fields in structure array
`mxGetFieldNameByNumber`	Pointer to field name from structure array, given field number
`mxGetFieldNumber`	Field number from structure array, given field name
`mxGetFieldByNumber`	Pointer to field value from structure array, given index and field number
`mxSetFieldByNumber`	Set field value in structure array, given index and field number
`mxAddField`	Add field to structure array
`mxRemoveField`	Remove field from structure array

Cell

`mxCreateCellMatrix`	2-D cell array
`mxCreateCellArray`	N-D cell array
`mxIsCell`	Determine whether mxArray is cell array
`mxGetCell`	Pointer to element in cell array
`mxSetCell`	Set contents of cell array

Delete and Duplicate mxArray

`mxDestroyArray`	Free dynamic memory allocated by MXCREATE* functions
`mxDuplicateArray`	Make deep copy of array

Convert mxArray

expand all

Numeric

`mxMakeArrayComplex`	Convert real `mxArray` to complex, preserving real data
`mxMakeArrayReal`	Convert complex `mxArray` to real, preserving real data

Character

`mxArrayToString`	Array to string
`mxArrayToUTF8String`	Array to string in UTF-8 encoding
`mxGetString`	`mxChar` array to C-style string or Fortran `character` array

Structure

mxSetClassName Structure array to MATLAB object array

Data Memory Management

`mxCalloc`	Allocate dynamic memory for array, initialized to 0, using MATLAB memory manager
`mxMalloc`	Allocate uninitialized dynamic memory using MATLAB memory manager
`mxRealloc`	Reallocate dynamic memory using MATLAB memory manager
`mxFree`	Free dynamic memory allocated by mxCalloc, mxMalloc, mxRealloc, mxArrayToString, or mxArrayToUTF8String functions

Asserts

`mxAssert`	Check assertion value for debugging purposes
`mxAssertS`	Check assertion value without printing assertion text

Constants

`mxIsInf`	Determine whether input is infinite
`mxIsFinite`	Determine whether input is finite
`mxIsNaN`	Determine 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.

C Matrix API

C Data Types

mxArray Attributes

Create, Query, and Access Data Types

Numeric Types

Noncomplex Float

Noncomplex Integer

Complex Float

Complex Integer

Sparse

Nonnumeric Types

Character

Logical

Object

Structure

Cell

Delete and Duplicate mxArray

Convert mxArray

Numeric

Character

Structure

Data Memory Management

Asserts

Constants

Topics

Related Information