Main Content

C++ MATLAB Data API Shared Library Support for Strongly Typed MATLAB Code

When creating C++ shared libraries from MATLAB® functions or classes, you can stipulate how to represent MATLAB data types in C++ application code by using standard and custom data type mappings between MATLAB and C++. To specify the data type requirements, you 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}.

Sample MATLAB Function with Strongly Typed Data

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

Sample MATLAB Class with Strongly Typed Data

classdef MyPosition
    properties
        X (1,1) double {mustBeReal}
        Y (1,1) double {mustBeReal}
    end
end

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

When you compile a strongly typed MATLAB function, class, or package, MATLAB Compiler SDK™ generates a C++ shared library header (.hpp file) and a deployable archive (.ctf file). To generate the header file from the MATLAB command prompt, enter the mcc command using this syntax:

mcc -W 'cpplib:<library_name>,generic' <MATLAB file(s) and/or package folder(s)> -d <output folder>

Tip

To generate the header file using the Library Compiler app:

  1. In the Type section of the toolstrip, click C++ Shared Library.

  2. In the Exported Functions section of the toolstrip, add the relevant MATLAB files.

  3. In the API selection section, select the Create interfaces that use the MATLAB Data API and Strongly Typed Interface option, and click Package.

The header file (.hpp) is generated in the same place as the deployable archive (.ctf) in the v2\generic_interface folder.

The generated header file:

  • Maps strongly typed MATLAB data types to C++ data types. For an example, see Create C++ MATLAB Data API Shared Library Header from Strongly Typed MATLAB Function.

  • Contains C++ namespaces that correspond to MATLAB package directories of the same name. For an example, see Deploy MATLAB Classes to C++ Application Using MATLAB Data API.

  • 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.

Mapping of Strongly Typed MATLAB Class to C++ Header File

Strongly Typed MATLAB ClassSnippet of C++ Header File
classdef MyRectangle

    properties
        UpperLeft  (1,1) shapes.MyPosition
        LowerRight (1,1) shapes.MyPosition
    end
    methods
        function R = enlarge(R, n)
            arguments
                R (1,1) shapes.MyRectangle
                n (1,1) double {mustBeReal}
            end
            % code
        end
        function R = show(R)
            arguments
                R (1,1) shapes.MyRectangle
            end
            % code
        end
    end
end

namespace shapes {
    class MyRectangle : public MATLABObject<MATLABControllerType> { 
    public:

        // constructors
        MyRectangle() : MATLABObject() {}

        // code

        // properties
        shapes::MyPosition getUpperLeft() {
            // code
        }
        void setUpperLeft(shapes::MyPosition obj) {
            // code
        }
        shapes::MyPosition getLowerRight() {
            // code
        }
        void setLowerRight(shapes::MyPosition obj) {
            // code
        }

        // methods
        matlab::data::Array show() { 
            // code
        }

        matlab::data::Array enlarge(double n) { 
            // code
        }

    };
}

The generated header file (.hpp file) and the MatlabCppSharedLib.hpp header file are included in the C++ application code using #include directives. You can then compile and run the application.

Sample C++ Application Code Snippet

#include "MatlabCppSharedLib.hpp"
#include "output/cpp/v2/generic_interface/libshapesv2.hpp" //header file generated by mcc

int main(const int argc, char *argv[]) {
    try {
        // common starter code that can apply to any application
        auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
        std::vector<std::u16string> OPTIONS = {u"-nojvm"};
        auto appPtr = matlab::cpplib::initMATLABApplication(mode, OPTIONS);
        std::string ctfName(argv[1]);
        auto libPtr = matlab::cpplib::initMATLABLibrary(appPtr, std::u16string(ctfName.cbegin(), ctfName.cend()));
        std::shared_ptr<MATLABControllerType> matlabPtr(std::move(libPtr));

        // application specific code that relies on the generated header
        shapes::MyPosition p1(matlabPtr);
        ...
        shapes::MyRectangle r1(matlabPtr);
        ...
    }
}

Tip

  • When writing C++ application code, you must include the header file (.hpp file) generated by the mcc command or the Library Compiler app and the MatlabCppSharedLib.hpp header file using #include directives.

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

  • During the compilation process, strongly typed information is retrieved only from arguments and properties blocks. The information retrieved consists of array size, type, and whether it is a real number.

See Also

|

Related Topics