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 C++ Shared Library Compiler app:

  1. In the Exported Functions section, add the relevant MATLAB files.

  2. In theC++ API selection section, select the Create interface that uses the MATLAB Data API for C++ option, and click Build and Package.

The header file (.hpp) is generated in the same place as the deployable archive (.ctf) in the output 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 C++ Shared 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

|

Topics