Write MATLAB Code for Strongly Typed C++ Interface

When creating a strongly typed C++ interface to MATLAB® functions or classes, you can specify how to represent MATLAB data types in C++ by using standard and custom data type mappings between MATLAB and C++. To specify the data type requirements, use an arguments block within a MATLAB function or a properties block and arguments block within a MATLAB class. For example, if your C++ application code uses a float data type to represent a real scalar double value, its equivalent representation in MATLAB is (1,1) single {mustBeReal}.

MATLAB Function with Strongly Typed Data

This strongly typed MATLAB function specifies data type requirements using an arguments block.

function r = stronglyTypedFun(num)
arguments
    num (1,1) single {mustBeReal}
end
r = magic(num);

For details, see Data Type Mappings Between C++ and Strongly Typed MATLAB Code.

When you compile a strongly typed MATLAB function, class, or namespace, MATLAB generates a C++ header (.hpp file). To generate the header file from the MATLAB command prompt, call matlab.engine.typedinterface.generateCPP.

The generated header file:

  • Maps strongly typed MATLAB data types to C++ data types.

  • Contains C++ namespaces that correspond to MATLAB namespace folders of the same name.

  • Contains C++ classes that correspond to MATLAB classes of the same name.

  • Contains public C++ methods that correspond to the public methods of MATLAB classes. The method names are unchanged and can be used as is in the C++ application code. These aligned names eliminate the need for intermediate layer top-level functions that call the class methods through an feval function execution.

  • Contains C++ get and set methods for public properties of MATLAB classes. The property names of MATLAB classes are prepended with get or set. For example, if the property name in a MATLAB class is UpperLeft, the corresponding C++ method names are getUpperLeft and setUpperLeft.

The strongly typed MATLAB class in this table specifies data type requirements using a properties block and arguments blocks. The table shows how the strongly typed MATLAB class in a Shapes namespace is translated into a C++ header file.

MATLAB Class with Strongly Typed Data

Strongly Typed MATLAB ClassSnippet of C++ Header File
classdef Position
 
    properties (Access = private)
        X (1,1) double {mustBeReal}
        Y (1,1) double {mustBeReal}
    end
 
    methods
 
        function d = calcDistanceOrigin(obj)
        % Calculates distance from origin (0,0)
            arguments (Output)  
                d (1,1) double {mustBeReal}
            end
 
            d = sqrt(obj.X^2 + obj.Y^2);
 
        end
 
        function [x, y] = getCoords(obj)
        % Returns the coordinates of the Position as 
        % 2 doubles in (X,Y) style
            arguments (Output)
                x (1,1) double {mustBeReal}
                y (1,1) double {mustBeReal}
            end
 
            x = obj.X;
            y = obj.Y;
 
        end
 
 
        function obj = setCoords(obj, x, y)
        % sets the coordinates of Position as 
        % 2 doubles in (X,Y) style and
        % returns the resulting Position value object
            arguments (Input)
                obj (1,1) Position
                x   (1,1) double {mustBeReal}
                y   (1,1) double {mustBeReal}
            end
            arguments (Output)
                obj (1,1) Position
            end
 
            obj.X = x;
            obj.Y = y;
 
        end
 
    end
end
 
#include "MatlabTypesInterface.hpp"
#include <map>
 
class Position : public MATLABObject<MATLABControllerType> {
    public:
 
    // constructors
    Position() : MATLABObject() {}
 
    Position(std::shared_ptr<MATLABControllerType> matlabPtr) :
    MATLABObject(matlabPtr, u"Position")
    {}
 
    Position(std::shared_ptr<MATLABControllerType> matlabPtr, 
    matlab::data::Array obj) :
    MATLABObject(matlabPtr, obj)
    {}
 
    // methods
    Position setCoords(double x, double y) {  
        // output is a Position object, not matlab::data::Array
        // implementation
    }
 
    std::tuple<double, double> getCoords() {  
        // output is a tuple with clear C++ types, 
        // not std::vector<matlab::data::Array>
        // implementation
    }
 
    double calcDistanceOrigin() {  
        // output is a double
        // implementation
    }
 
};

Sample C++ Application Code Snippet

Include the generated header file (.hpp file) in the C++ application code by using #include directives. You can then compile and run the application.

#include "MatlabEngine.hpp"
#include "myApp.hpp"
 
int main() {
 
    // Connect to MATLAB
 
    std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = matlab::engine::startMATLAB();
    matlab::data::ArrayFactory arrayFactory;
 
    // Create a position object
    p1 = Position(matlabPtr);
 
    // Set the (X,Y) coordinates of the Position value-object
    Position p2 = p1.setCoords(3.0, 4.0);  // output is obtained as a Position natively in C++
 
 
    // Get the distance from origin of the Position
    double dist = p2.calcDistanceOrigin(); // Note native C++ type
 
    // Get the (X,Y) coordinates of the Position value-object from the tuple<double,double> output
    double x;
    double y;
    std::tie(x,y) = getCoords();
 
}

Tip

  • When writing C++ application code, you must include the header file (.hpp file) generated by the matlab.engine.typedinterface.generateCPP function and the MatlabEngine.hpp header file by using #include directives.

    For examples building engine applications, see Integrate Strongly Typed MATLAB Data in C++ Application.

  • Your MATLAB code must be strongly typed to leverage all the features of the interface. Otherwise, data type mapping between MATLAB and C++ is absent, and you cannot use native C++ data types.

    The MATLAB function must be on your MATLAB path.

  • During generation of the strongly typed interface, the matlab.engine.typedinterface.generateCPP function retrieves type information from arguments and properties blocks. The retrieved information is array size, type, and whether it is a real number.

See Also

| |

Topics