Main Content

MATLAB Object for C++ Arrays

MATLAB® provides the clib.array interface to wrap C++ native arrays and std::vector types. The term clib array refers to the MATLAB representation of these C++ types.

A MATLAB clib array is defined only when the corresponding C++ native array or std::vector type is used by supported C++ constructs — function input and output arguments and data members. The library header files must contain the definition of the array element type. The constructs must be supported by MATLAB and included when building the MATLAB interface to the C++ library.

This topic shows how to create a MATLAB clib array, use a clib array as a C++ function parameter, and convert a MATLAB array to a C++ array object. This topic also describes the common properties and methods of all MATLAB clib arrays.

Create MATLAB Array of C++ Objects

To create a MATLAB object that represents C++ native arrays or std::vector types, call the MATLAB clibArray function. For example, suppose that your interface libname defines a class named myclass. In MATLAB, you refer to this class as clib.libname.myclass. Create an array of five myclass objects.

myclassArray = clibArray("clib.libname.myclass",5);

The type of the MATLAB array myclassArray is clib.array.libname.myclass. To access an element of myclassArray, use MATLAB indexing. For example, access the first element.

e = myclassArray(1)

The element type is clib.libname.myclass.

Alternatively, if the element type is a fundamental type, a user-defined class with a default constructor, or a standard string type, call the clib.array constructor.

To create an array from a fundamental type, you must know the corresponding element type. For mapping information, see the Vector Integer Types and Floating Point Types tables in C++ to MATLAB Data Type Mapping. For example, if the C++ type is std::vector<int32_t>, then the MATLAB element type is clib.libname.Int. Create an array with five clib.libname.Int elements.

myIntArray = clib.array.libname.Int(5)

Create an array of five elements of the same user-defined class.

myclassArray = clib.array.libname.myclass(5)

To create an array from a standard string type, see the std::vector<T> String Types table for element type information. For example, if the C++ type is std::vector<std::string>, then the MATLAB element type is clib.libname.std.String. Create an array with five clib.libname.std.String elements.

myStringArray = clib.array.libname.std.String(5)

Treat C++ Native Arrays of Fundamental Type as MATLAB Fundamental Types

By default, MATLAB represents C++ native arrays of fundamental types with the MATLAB clib.array types. If you need to preserve fundamental MATLAB array types with outputs, then build your MATLAB interface to the C++ library with the ReturnCArrays argument set to false. For more information, see clibgen.generateLibraryDefinition.


Saving C++ objects into a MAT-file is not supported.


You cannot create an array of C++ objects using square brackets.

Call C++ Function with clib.array Parameter

You can create a MATLAB variable to pass as a parameter for specific C++ types. These examples show how to pass a clib parameter directly, by reference, as a fixed-size array, to update array elements, and as const and non-const objects. The code assumes you build an interface named libname.

std::vector Parameter

When you pass a clib array directly as a parameter to a C++ function that expects an std::vector input, MATLAB converts the elements and the size of the clib array to an std::vector argument. The number of dimensions of the passed array must match the expected dimensions of the parameter. For example, this function takes an std::vector of type double.

void fcn(std::vector<double> doubleVec);

Display the function signature from MATLAB.

help clib.libname.fcn
fcn -  clib.libname.fcn Representation of C++ function fcn.

    Input Arguments
      doubleVec      vector clib.array.libname.Double

Create a 1-D clib array and pass it to fcn.

arr1d = clibArray("clib.libname.Double",[3])

If you pass a 2-D array, MATLAB returns an error.

arr2d = clibArray("clib.libname.Double",[2 3]);
ans =
     2     3
Error using clib.libname.fcn
No method 'clib.libname.fcn' with matching signature found.

Fixed-Sized Array Parameter

If the parameter is a fixed-sized array, then the number of dimensions and the type of the elements of a passed array must match those of the expected parameter. For example, this function takes a fixed-sized array of type double.

void fcn(double arr[3]);

Display the function signature from MATLAB.

help clib.libname.fcn
fcn -  clib.libname.fcn Representation of C++ function fcn.

    Input Arguments
      arr            3 element vector clib.array.libname.Double  

Then call the function with a clib array of the required size and type.

arr3 = clibArray("clib.libname.Double",3); 

Pass by Reference Parameter

You can pass a clib array to a C++ function that modifies the input data and returns the data to MATLAB. Then convert the data from the clib array to a MATLAB array using one of the methods listed in MATLAB C++ Object Array Methods. For example, these functions populate C++ arrays with data of type int32_t and char.

#include <cstdint>
#include <vector>

void getData(std::vector<int32_t>& arr) {
   int32_t data [] = {2, 4, 5};
   for (auto c : data) {
void getData(std::vector<char>& arr) {
   char data [] = {'M', 'A', 'T', 'L', 'A', 'B', '\0'};
   for (auto c : data) {

Call the getData function to populate a numeric clib array of type int32_t and convert it to a MATLAB int32 array.

narr = clib.array.libname.Int(3);
ans = 1×3 int32 row vector    
   2   4   5

Now call the getData function to populate a character array and convert it for use in MATLAB.

carr = clib.array.libname.Char(1);
ans = 'MATLAB '

Updated Array Elements

If a C++ function updates the elements of an array parameter, then the function also updates the MATLAB clib array because the array is a MATLAB handle. For example, this function modifies the elements of the parameter doubleArr.

void fcn(double * doubleArr, int size) { 
    for(int i = 0; i < size; ++i) 
        doubleArr[i] *= 2.0; 

To create interface libname, edit the definelibname.m definition file. Uncomment the statements defining fcn and replace <SHAPE> with "size". Display the function signature from MATLAB.

help clib.libname.fcn
fcn -  clib.libname.fcn Representation of C++ function fcn.

    Input Arguments
      doubleArr      vector clib.array.libname.Double  

Then call this function from MATLAB to update the array elements with double their values.

doubleArr = clibConvertArray("clib.libname.Double", [2 3 4]); 
doubleArr(3) % display element 3
ans = 

const and Non-const Parameters

A const parameter can take a non-const object, but a non-const parameter cannot take a const object. For example, this C++ class has functions that create const and non-const objects and methods that take const and non-const inputs.

class MyClass {
      int m_value;
      MyClass():m_value(0) {}
      void nonConstMethod() {}
      int constMethod() const { return m_value; }
} classObj;

MyClass& funcNonConstObj() {
    return classObj;

const MyClass& funcConstObj() {
    return classObj;

Display the function signatures from MATLAB.

help clib.libname.funcConstObj
funcConstObj -  clib.libname.funcConstObj Representation of C++ function funcConstObj.

  RetVal = clib.libname.funcConstObj
    Output Arguments
      RetVal         read-only clib.libname.MyClass  
help clib.libname.funcNonConstObj
funcNonConstObj -  clib.libname.funcNonConstObj Representation of C++ function funcNonConstObj.

  RetVal = clib.libname.funcNonConstObj
    Output Arguments
      RetVal         clib.libname.MyClass  

Create MyClass objects obj1 and obj2.

obj1 = clib.libname.funcConstObj;
obj2 = clib.libname.funcNonConstObj;

Confirm that the const object is read-only, and then pass it to its constMethod and nonConstMethod methods.

ans = 
Error using clib.libname.MyClass/nonConstMethod
Calling nonconst method 'nonConstMethod' of read-only object 'clib.libname.MyClass' not supported.

However, you can pass the non-const object to both of its constMethod and nonConstMethod methods.

ans = 

Convert MATLAB Array to C++ Array Object

You can use an existing MATLAB array as a C++ array object. Call the clibConvertArray function. For example, suppose that you have a MATLAB interface libname. Convert a MATLAB array of double values to a C++ array object by using the clibConvertArray function.

a = [1 2 3];
arr = clibConvertArray("clib.libname.Double",a);

MATLAB C++ Object Array Properties

MATLAB arrays created with clibArray or clibConvertArray have these properties.





double vectorRead-only

C++ dimensions of the array. For example, [2 5 3] specifies a 2-by-5-by-3 array.


logical scalarRead-only

  • true — You can add or remove elements.

  • false — You cannot add or remove elements.

MATLAB C++ Object Array Methods

MATLAB arrays created with clibArray or clibConvertArray have these methods.






Add an optionally specified element to the end of the array.

For a primitive MATLAB clib array, if there is no input argument, then a zero value is appended.

For a class-type MATLAB clib array, if there is no input argument, then the class-type default constructor is appended. If the class-type default constructor is deleted, a run-time error occurs.



Remove the last element of the array. If the MATLAB clib array is empty, a run-time error occurs.



Convert to double precision.



Convert to int8.



Convert to uint8.



Convert to int16.



Convert to uint16.



Convert to int32.



Convert to uint32.



Convert to int64.



Convert to uint64.



Convert to logical.

Memory Management

The memory for MATLAB arrays created with clibArray or clibConvertArray is owned and managed by MATLAB. You do not need to explicitly release the memory for clib arrays. For more information about releasing memory for C++ objects from MATLAB, see clibRelease.

See Also

| | |

Related Topics