C++ to MATLAB Data Type Mapping - MATLAB & Simulink (original) (raw)

These tables show how MATLAB® converts C/C++ data into equivalent MATLAB data types. MATLAB uses these mappings when creating library definition files. Use this information to help you define missing information for MATLAB signatures.

Numeric Types

Scalar Integer Types

Fixed-width integer data type mappings are independent of the platform and compiler. The mappings for non-fixed-width integer types are based on the compiler.

Fixed-Width Integer Types. For these types, specify DIRECTION as "input" and SHAPE as 1.

Non-Fixed-Width Integer Types. MATLAB supports these non-fixed-width C integer types. Based on the compiler used, MATLAB maps these types to the corresponding fixed-width C types, as shown in the Fixed-Width Integer Types table.

• short
• short int
• signed short
• signed short int
• unsigned short
• unsigned short int
• int
• signed int
• unsigned
• unsigned int
• long
• signed long
• signed long int
• unsigned long
• unsigned long int
• long long

Vector Integer Types

This table shows how MATLAB data types correspond to std::vector types. By default, MATLAB represents std::vector types with the MATLABclib.array type. For more information, see Represent C++ Arrays Using MATLAB Objects.

MATLAB converts the names of fundamental C++ types to upper camel case. For complex types, MATLAB adds std.complex to the clib.array type.

For these types, specify DIRECTION as "input" and SHAPE as 1.

Floating Point Types

For these types, specify DIRECTION as "input" and SHAPE as 1.

String and Character Types

These tables show how C++ string and char data types correspond to MATLAB data types. The data mapping depends on how the type is used in the function, as a parameter, return type, or data member (property). For example, these function definitions show different uses of type T.

void fcn(T);  // T is a parameter type (MATLAB input argument)
T fcn();      // T is a return type (MATLAB output argument)

Plain C++ Character and String Types

For these types, specify DIRECTION as "input" and SHAPE as 1.

C++ char* and char[] Types

C++ Array of Strings

MATLAB does not support these const and non-const C++ return types.

• char** and char*[]
• wchar_t** and wchar_t*[]
• char16_t** and char16_t*[]
• char32_t** and char32_t*[]

std::vector<T> String Types

For these types, specify DIRECTION as"input".

bool Types

For these types, specify DIRECTION as "input" andSHAPE as 1.

Static Data Members

MATLAB treats public static and public const static data members as read-only properties. You cannot update the value of a static data member. For example, build an interface lib to this header file.

class Set
{
   public:
   static int p1;
   const static int p2;
};
int Set::p1 = 5;
const int Set::p2 = 10;

The help for clib.lib.Set shows p1 andp2 as properties. To use the properties in MATLAB:

res = clib.lib.Set.p1 + clib.lib.Set.p2

Do not update a static property by using the class name. If you do, then MATLAB creates a structure named clib. You must manually clear theclib structure before calling any functions in the interface. For example, if you try to update static property p1, thenclib is a variable:

Clear the variable before calling any commands in clib.lib.

clear clib clib.lib.Set.p1

For information about using static properties as SHAPE arguments, seeUse Property or Method as SHAPE.

const Types

MATLAB treats an object of a C++ read-only class as a const object. The name of the object is the C++ class name, and MATLAB adds "read-only" text to the object display. For example, create a MATLAB interface to this library MyClass:

const class MyClass 
{ 
    public: 
        int val1; 
        int val2; 
}; 
 
const MyClass& func(); 

Call the function func in MATLAB to create a const MyClass object:

res = clib.MyClass.func()

res =
read-only MyClass with properties: val1: 1 val2: 2

To check if the object is const, call clibIsReadOnly.

The function returns logical 1 (true) if the object is read-only. Otherwise, it returns logical 0 (false).

User-Defined Types

Class and Struct Types

In some situations, you can pass MATLAB struct arrays as C++ struct array arguments. For more information, see Supported struct Types.

This table shows how to configure a C++ parameter type T in the definition file for a MATLAB interface to library libname, whereT is a class or a struct.

This table shows how to configure a C++ return type T.

This table shows how to configure a C++ data member type T.

Supported struct Types

Since R2024b

MATLAB supports C++ structures, including nested structures, that meet these conditions:

• Contain public fundamental and non-fundamental data members.
• Array data members must be fully defined.
• The data member field names must be valid MATLAB names.

The structure does not contain:

• Constructors
• Destructors
• Copy constructors
• Assignment operators
• const members
• Static member initializers
• Base classes
• Virtual methods
• Inner classes
• Anonymous inner structs
• Unions
• Data Members with default values
• Structures with circular reference

For information about passing a MATLAB structure as a C++ struct argument, see Pass struct Parameter.

Enumerated Types

This table shows how to configure a C++ enum type T in the definition file for a MATLAB interface to library libname, whereT is an enumerated type.

nullptr Argument Types

nullptr Input Argument Types

MATLAB provides a clib.type.nullptr type so that you can pass NULL to a function with these C++ input argument types:

• Pointers to objects. However, pointers to fundamental MATLAB array types are not supported.
• shared_ptr
• Arrays

The clib.type.nullptr type is supported for these MATLAB argument types:

• scalar object pointers
• clib arrays

nullptr Return Types

The C++ interface returns type-specific empty values for functions that return nullptr.

• For type double,​ MATLAB returns [] for the valuedouble.empty.
• For all other fundamental types,​ MATLAB returns an _`MLTYPE`_.empty value. To determine MLTYPE, look for the C or C++ type in the tables in this topic. MLTYPE is in theEquivalent MATLAB Type column.
  To test for nullptr types, call the isempty function.
• For non-fundamental types,​ MATLAB returns a nullptr object. To test fornullptr objects, call the clibIsNull function.

void* Argument Types

To pass void* arguments to and from C++ functions, see Define void* and void** Arguments. MATLAB does not support void* data members.

When passing a void* input argument, MATLAB converts the underlying data to the corresponding C++ type.

Fundamental Types Mapping

clib.array Types Mapping

typedef void* Mapping

Unsupported Data Types

If the data type of an argument/return type in a class constructor, method, or function is one of these types, or if the library contains any unsupported language features, then the functionality is not included in the MATLAB interface to the library.

• Any type with a size greater than 64 bits, for example long double
• References to a pointer, for example int*&
• Pointers or arrays of std::string
• Pointers or references to enumerations
• Vectors of pointers to class objects, for examplestd::vector<Myclass*>
• Reference data members
• void* data members
• Multidimensional data member arrays
• Modifying static data members
• ** pointers, except:
  • MATLAB supports char** types.
  • MATLAB supports ** pointers to custom classes used as function or ​method parameter types.
  • MATLAB supports void** used as function or method parameter types.
• Multilevel pointers, such as _`type`_***
• C function pointers and std::function as function return types or data members. You also cannot pass a MATLAB function as input to C function pointers orstd::function parameter.
• Class templates with incomplete or no instantiations
• union
• Types defined in the std namespace, except these supported types:
  • std::string
  • std::wstring
  • std::u16string
  • std::u32string
  • std::vector
  • std::shared_ptr
  • std::function
  • std::complex

Messages About Unsupported Types

MATLAB reports on constructs that use unsupported types. To view these messages, use the Verbose option in the clibgen.generateLibraryDefinition or clibgen.buildInterface functions.

For example, suppose that functionName inClassName is defined in HeaderFile.h. If an argument to functionName is of unsupported type_type_, then MATLAB does not add functionName to the definition file. In addition, if Verbose is true, thenclibgen.generateLibraryDefinition displays this message.

Did not add member 'functionName' to class 'ClassName' at HeaderFile.h:290.   'type' is not a supported type.

See Also

clibgen.generateLibraryDefinition | clibgen.buildInterface | clibIsReadOnly

Related Topics

• Define MATLAB Interface for C++ Library
• Represent C++ Arrays Using MATLAB Objects