Data Types for Passing MEX Function Data

The MATLAB® Data API supports array types that enable MEX functions to pass specific data types from and to MATLAB. For information on additional array types, see MATLAB Data API for C++.

The most general type of array is the matlab::data::Array. More specific types provide additional functionality. For example, matlab::data::TypedArray<T> provides iterator support and matlab::data::CharArray provides converters for ASCII and UTF16 types.

The following sections show how to define input and output types using the MATLAB Data API. Assume a MEX framework with inputs and outputs defined as shown in the following class definition. Use the matlab::data::ArrayFactory to create output arrays.

class MexFunction : public matlab::mex::Function {
public:
    void operator()(matlab::mex::ArgumentList outputs, matlab::mex::ArgumentList inputs) {
        matlab::data::ArrayFactory factory;
        ...
    }

Typed Arrays

Use matlab::data::TypedArray<T> to define specific types, such as numeric and logical values. For example, call myMexFcn from MATLAB.

m = [-2 2 6 8];
result = myMexFcn(m);

Assign input of MATLAB type double in the MEX function.

matlab::data::TypedArray<double> doubleArray = inputs[0];

Return output to be of type double in MATLAB:

outputs[0] = factory.createArray<double>({ 1,4 }, { -2.0, 2.0, 6.0, 8.0 });

Character Arrays

Use matlab::data::CharArray to pass character arrays to and from MEX functions. For example, call myMexFcn from MATLAB with a character vector.

result = myMexFcn('Character vector');

Assign input of MATLAB type char in the MEX function.

matlab::data::CharArray charVector2 = inputs[0];

Return output to be of type char in MATLAB.

outputs[0] = factory.createCharArray("Character vector");

String Arrays

Use matlab::data::TypedArray<MATLABString> to pass string arrays to and from MEX functions. For example, call myMexFcn from MATLAB with a string array.

result = myMexFcn(["Array", "of", "strings"]);

Assign input of MATLAB type string in the MEX function.

matlab::data::TypedArray<matlab::data::MATLABString> stringArray = inputs[0];

Return output to be of type string in MATLAB.

outputs[0] = factory.createArray({ 1,3 }, { u"Array", u"of", u"strings" });

Cell Arrays

Use matlab::data::CellArray to pass cell arrays to and from MEX functions. For example, call myMexFcn from MATLAB with a cell array.

result = myMexFcn({'MATLAB cell array', [1.2 2.2; 3.2 4.2]});

Assign input of MATLAB type cell in the MEX function.

matlab::data::CellArray inCellArray2 = inputs[0];

Return output to be of type cell in MATLAB.

outputs[0] = factory.createCellArray({ 1,2 },
                factory.createCharArray("MATLAB Cell Array"),
                factory.createArray<double>({ 2,2 }, { 1.2, 3.2, 2.2, 4.2 }));

Note the row-major vs. column-major ordering difference between C++ and MATLAB when defining 2-D arrays.

Structure Arrays

Use matlab::data::StructArray to pass structures to and from MEX functions. For example, call myMexFcn from MATLAB with a structure.

st.Name = 'Color';
st.Value = uint8([1 0 1]);
result = myMexFcn(st);

Assign input of MATLAB type struct in the MEX function.

matlab::data::StructArray inStructArray = inputs[0];

Return output to be of type struct in MATLAB.

matlab::data::StructArray S = factory.createStructArray({ 1,1 }, { "Name","Value" });
S[0]["Name"] = factory.createCharArray("Color");
S[0]["Value"] = factory.createArray<uint8_t>({ 1, 3 }, { 1, 0, 1 });
outputs[0] = S;

MATLAB Objects

Use matlab::data::Array to pass objects to and from MEX functions. For example, call myMexFcn from MATLAB with an object of the user-defined class named MyClass.

classdef MyClass
    property 
        MeanValue = 0.5
    end
end
obj = MyClass;

Assign input of MATLAB type MyClass in the MEX function.

matlab::data::Array obj = inputs[0];

Assume that MyClass defines a property called MeanValue that contains a scalar double. Get the property value using getProperty. 

matlab::data::TypedArray<double> meanValue = matlabPtr->getProperty(obj, u"MeanValue");
double m = meanValue[0];

Set the property value using setProperty and return the object to MATLAB as a matlab::data::Array.

matlabPtr->setProperty(obj, u"MeanValue", factory.createScalar<double>(1.02));
outputs[0] = obj;

For an example of how to work with MATLAB objects, see MATLAB Objects in MEX Functions.

See Also

| | | |

Topics