MATLAB Object For C++ Arrays

MATLAB^® provides an interface, clib.array, which wraps 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 only defined when the corresponding C++ native array or std::vector is used by supported C++ constructs—function input and output arguments and data members. The provided headers must contain the definition of the element type. The construct must be supported by MATLAB and not dropped when building the interface.

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 library libname defines a class myclass. In MATLAB, you refer to this class as clib.libname.myclass. To create an array of five myclass objects, use this syntax:

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, to access the first element, use this syntax:

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 of five elements for a user-defined class, type:

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

To create an array from a fundamental type, you must know the element type. For more 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. To create an array with five elements, type:

myIntArray = clib.array.libname.Int(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. To create an array with five elements, type:

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

Note

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

Note

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

Convert MATLAB Array to C++ Array Object

You can use an existing MATLAB array as a C++ array object. Call the clibConvertArray function.

MATLAB C++ Object Array Properties

MATLAB arrays created with clibArray or clibConvertArray have these properties.

Property	Type	Access	Description
Dimensions	double vector	read-only	C++ dimensions of the array
Resizable	logical scalar	read-only	true—add/remove element allowed false—add/remove element not allowed

MATLAB C++ Object Array Methods

MATLAB arrays created with clibArray or clibConvertArray have these methods.

Method	Signature	Description
append	append([element])	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.
removeLast	removeLast	Remove the last element of the array. If the MATLAB clib array is empty, a run-time error occurs.
double	double	Convert to double precision.
int8	int8	Convert to int8.
uint8	uint8	Convert to uint8.
int16	int16	Convert to int16.
uint16	uint16	Convert to uint16.
int32	int32	Convert to int32.
uint32	uint32	Convert to uint32.
int64	int64	Convert to int64.
uint64	uint64	Convert to uint64.
logical	logical	Convert numeric values to logical.

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 interface with the ReturnCArrays argument set to false. For more information, see clibgen.generateLibraryDefinition.

Memory Management

The memory for MATLAB arrays created with clibArray or clibConvertArray is owned by MATLAB. To release the memory, call clibRelease.