Main Content

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 std::vector<T> Integer Types and std::vector<T> 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

TypeAccess

Description

Dimensions

double vectorread-only

C++ dimensions of the array

Resizable

logical scalarread-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 runtime error occurs.

removeLast

removeLast

Remove the last element of the array. If the MATLAB clib array is empty, a runtime 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.

See Also

| |

Related Topics