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.

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 matlab::engine::MATLABEngine::getProperty.

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

Set the property value using matlab::engine::MATLABEngine::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.