Handle Inputs and Outputs

The C++ MEX API provides features that enable you to access and validate arguments. Both matlab::mex::ArgumentList and matlab::data::Array define functions that are useful to perform checks on the arguments passed to the MEX function. The matlab::data::ArrayType enumeration class enables you to test for specific types of inputs.

Argument Validation

This table shows functions useful for error checking.

`matlab::mex::ArgumentList::size()`	Determine number of inputs. The size of the `ArgumentList` array is equal to the number of arguments used in the function call.
`matlab::mex::ArgumentList::empty()`	Test for no inputs or outputs. If the MEX function is called with no input or output arguments, then the respective `ArgumentList` argument is empty.
`matlab::data::Array::getType()`	Determine the type of an input argument. This function returns a `matlab::data::ArrayType` object.
`matlab::data::Array::getDimensions()`	Determine the dimensions of an input argument array. This function returns a `matlab::data::ArrayDimensions` object, which is defined as `std::vector<size_t>`.
`matlab::data::Array::getNumberOfElements()`	Determine the number of elements in an input argument array.
`matlab::data::Array::isEmpty()`	Determine if an input argument array is empty.

These examples show how to test argument values in your MEX file and throw errors in MATLAB^® when tests fail. Use the feval function to call the MATLAB error or warning functions.

Call feval with these arguments:

The error or warning function name, passed as a UTF16 string.
The number of returned arguments, which is zero in these examples.
The messages to display with the MATLAB error or warning functions. Pass the message in an std::vector containing the matlab::data::Array created using the matlab::data::ArrayFactory factory.

To call feval and define the arguments, get a pointer to a MATLAB engine and a MATLAB data array factory.

class MexFunction : public matlab::mex::Function {
public:
    void operator()(matlab::mex::ArgumentList outputs, matlab::mex::ArgumentList inputs) {
        std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();
        matlab::data::ArrayFactory factory;
        ...
    }
}

MEX file requires three input arguments.

if (inputs.size() != 3) {
    matlabPtr->feval(u"error", 0,
        std::vector<matlab::data::Array>({ factory.createScalar("Three inputs required") }));
}

MEX file requires the assignment of two output arguments.

if (outputs.size() != 2) {
    matlabPtr->feval(u"error", 0, 
        std::vector<matlab::data::Array>({ factory.createScalar("Two outputs required") }));
}

Second input argument must be a 1-by-4 row vector of noncomplex doubles.

if (inputs[1].getType() != matlab::data::ArrayType::DOUBLE ||
    inputs[1].getType() == matlab::data::ArrayType::COMPLEX_DOUBLE ||
    inputs[1].getNumberOfElements() != 4 || 
    inputs[1].getDimensions()[1] == 1) {
    matlabPtr->feval(u"error", 0, 
       std::vector<matlab::data::Array>({ factory.createScalar("Input must be 4-element row vector")}));
}

ArgumentList Iterators

The matlab::mex::ArgumentList container implements a pair of iterators that mark the beginning and end of the argument list. Use these iterators to loop over all the inputs to a MEX function. For example, this MEX function sums all its inputs using a range-based for loop.

#include "mex.hpp"
#include "mexAdapter.hpp"

class MexFunction : public matlab::mex::Function {
    matlab::data::ArrayFactory factory;
public:
    void operator()(matlab::mex::ArgumentList outputs, matlab::mex::ArgumentList inputs) {
        double sm = 0;
        for (const matlab::data::TypedArray<double>& elem : inputs) {
            sm = sm + elem[0];
        }
        outputs[0] = factory.createScalar(sm);
    };
};

Save this MEX file as sumInputs.cpp and compile with the mex command. Call the function with a range of arguments.

mex sumInputs.cpp
sumInputs(1,2,3,4,5,6,7)

ans =

    28

Support Variable Number of Arguments

You can support variable number of arguments in MEX functions by checking the size of the input and output matlab::mex::ArgumentList array.

In the following code snippet, the size of the outputs parameter array indicates how many outputs are specified when the MEX function is called. Using the ArgumentList::size function, this code determines how many outputs are specified when the MEX function is called.

void operator()(matlab::mex::ArgumentList outputs, matlab::mex::ArgumentList inputs) {

    if (outputs.size() == 3) {
        outputs[0] = // Assign first output
        outputs[1] = // Assign second output
        outputs[2] = // Assign third output
    }
    else if (outputs.size() == 1) {
        outputs[0] = // Assign only one output
    }
    else {
        matlabPtr->feval(u"error", 0, 
            std::vector<matlab::data::Array>({ factory.createScalar("One or three outputs required")}));
    }
}