Handle Inputs and Outputs - MATLAB & Simulink (original) (raw)

Main Content

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 theArgumentList 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 respectiveArgumentList argument is empty.
matlab::data::Array::getType() Determine the type of an input argument. This function returns amatlab::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 asstd::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 MATLABerror or warning functions.

Call feval with these arguments:

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 themex 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")}));
    }
}

See Also

matlab::mex::ArgumentList