Advantages of MATLAB Data API for C++ over MWArray API

MathWorks^® recommends deploying to C++ applications using the more modern MATLAB Data API over the mwArray API. The advantages of using the MATLAB Data API over the mwArray API are:

Difference in Generated Artifacts

When you feed a MATLAB function or class to the compiler.build.cppSharedLibrary function or the Library Compiler app, the main products generated are different for the two deployment options.

Assuming you have a MATLAB function called calculateDistance stored in a file named calculateDistance.m, and you want to deploy in a C++ application, let's examine the resulting outcomes of the two deployment alternatives:

function distance = calculateDistance(p1, p2)
    % This function calculates the Euclidean distance between two points
    % Inputs:
    %   p1 - a two-element vector [x, y]
    %   p2 - a two-element vector [x, y]
    % Output:
    %   distance - the Euclidean distance between p1 and p2
    
    % Use arguments block to map C++ type to corresponding MATLAB type
    % std::vector<int32_t> <--> (1,2) int32 {mustBeReal}
    
    arguments (Input)
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

    arguments (Output)
        distance (1,1) int32 {mustBeReal}
    end
    
    % Calculte Euclidean distance
    diff = p1 - p2;
    diffSq = diff.^2;
    sumSq = sum(diffSq);
    distance = sqrt(sumSq);
end

When you pass the calculateDistance.m file into the compiler.build.cppSharedLibrary function, the MATLAB Data API is the default choice. To use the mwArray API, you need to explicitly specify the interface type using the name-value pair Interface="mwarray".

results = compiler.build.cppSharedLibrary("calculateDistance.m",...
    OutputDir="calcDistMDArray", Verbose="on")

results = compiler.build.cppSharedLibrary("calculateDistance.m",...
    Interface="mwarray", OutputDir="calcDistmwArray", Verbose="on")

The function generates corresponding files for the two APIs in the specified folder:

P:\MATLAB\WORK\CALCDISTMDARRAY
│   GettingStarted.html
│   includedSupportPackages.txt
│   mccExcludedFiles.log
│   readme.txt
│   requiredMCRProducts.txt
│   unresolvedSymbols.txt
│
└───v2
    └───generic_interface
            calculateDistance.ctf
            calculateDistancev2.hpp
            readme.txt

P:\MATLAB\WORK\CALCDISTMWARRAY
    calculateDistance.cpp
    calculateDistance.def
    calculateDistance.dll
    calculateDistance.exp
    calculateDistance.exports
    calculateDistance.h
    calculateDistance.lib
    GettingStarted.html
    includedSupportPackages.txt
    mccExcludedFiles.log
    readme.txt
    requiredMCRProducts.txt
    unresolvedSymbols.txt

No subfolders exist

When using the MATLAB Data API to incorporate MATLAB code into a C++ application, MATLAB Compiler SDK does not output a C++ shared library file. When you pass a MATLAB function or class to the compiler.build.cppSharedLibrary function or the Library Compiler app, the main products generated are a code archive (.ctf file) and a header (.hpp file). This design offers a more streamlined interface for C++ developers.

To generate a C++ shared library file from MATLAB code with MATLAB Compiler SDK, you must use the mwArray API. Yet, this API operates on the older C++03 standard and lacks many of the sophisticated features provided by the MATLAB Data API. In addition, it transfers data less efficiently.

Support for Strong Types Using MATLAB Data API

You have the flexibility to dictate how MATLAB interprets and handles C++ data types.

If you are deploying a MATLAB class use a properties block and arguments block within the MATLAB class.

% .m file
arguments
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

// .hpp file
   
std::vector<int32_t> p1, 
std::vector<int32_t> p2)

// .cpp file
  
std::vector<int32_t> p1 = { 0, 0 };
std::vector<int32_t> p2 = { 3, 4 };