matlab::cpplib::MATLABLibrary::feval

Execute a MATLAB function from a deployable archive

Description

Execute a function with 1 output MATLAB^® Data Array argument; 1 input MATLAB Data Array argument

function name as u16string

matlab::data::Array feval(const std::u16string &function, const matlab::data::Array &arg, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

matlab::data::Array feval(const std::string &function, const matlab::data::Array &arg, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with 1 output MATLAB Data Array argument; 0, 2, or more input MATLAB Data Array arguments

function name as u16string

matlab::data::Array feval(const std::u16string &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

matlab::data::Array feval(const std::string &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with 0, 2, or more output MATLAB Data Array arguments; any number of input MATLAB Data Array arguments

function name as u16string

std::vector<matlab::data::Array> feval(const std::u16string &function, const size_t nlhs, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

std::vector<matlab::data::Array> feval(const std::string &function, const size_t nlhs, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with native input and output arguments

function name as u16string

template<class ReturnType, typename...RhsArgs> ReturnType feval(const std::u16string &function, RhsArgs&&... rhsArgs)

function name as string

template<class ReturnType, typename...RhsArgs> ReturnType feval(const std::string &function,RhsArgs&&... rhsArgs)

Execute a function with native input and output arguments, with output redirection

function name as u16string

template<class ReturnType, typename...RhsArgs> ReturnType feval(const std::u16string &function, const std::shared_ptr<StreamBuffer> &output, const std::shared_ptr<StreamBuffer> &error, RhsArgs&&... rhsArgs)

function name as string

template<class ReturnType, typename...RhsArgs> ReturnType feval(const std::string &function, const std::shared_ptr<StreamBuffer> &output, const std::shared_ptr<StreamBuffer> &error, RhsArgs&&... rhsArgs)

Call a packaged MATLAB function within a C++ shared library:

• Without redirection of standard output or standard error

• With redirection of standard output

• With redirection of standard output and standard error

LhsItem	One of the following: Native scalar std::vector of a native type matlab::data::Array std::tuple of any combination of any of the previously mentioned possibilities.
RhsArgs	A sequence of zero or more arguments which are one of the following: Native scalar std::vector of a native type matlab::data::Array
StreamBuffer	std::basic_streambuf<char16_t>

MATLABLibrary::feval calls a packaged MATLAB function within a C++ shared library and passes the name of the function, followed by the arguments. If the specified function cannot be found in the library, an exception is thrown. By default, the function returns either a single matlab::data::Array object (if one output argument is expected) or a vector of matlab::data::Array objects (if zero or multiple output arguments are expected). In the former case, the vector is empty. By specifying a template argument, you can specify an alternative return type, which can be a primitive type, or a vector of primitive types, or a tuple of multiple instances of either.

Supported native types:

• bool

• int8_t

• int16_t

• int32_t

• int64_t

• uint8_t

• uint16_t

• uint32_t

• uint64_t

• float

• double

• std::string

• std::u16string

• std::complex<T> where T is one of the numeric types.

• Native C++ data passed as input is converted into the corresponding MATLAB types.

• std::vector is converted into a column array in MATLAB.

• The result of a MATLAB function is converted into the expected C++ data type if there is no loss of range.

• Otherwise, an exception is thrown.

Parameters

const std::u16string &function const std::string &function	The name of a compiled MATLAB function to be evaluated specified either as u16string or string.
const size_t nlhs	The number of return values.
const std::vector<matlab::data::Array>& args	Arguments used by the MATLAB function when more than one is specified.
const matlab::data::Array>& arg	Argument used by the MATLAB function with single input.
const RhsArgs& rhsArgs	Template parameter pack consisting of a sequence of zero or more arguments, each of which is one of the following: a bare native type (see list of supported native types) a std::vector of a bare native type a matlab::data::Array
const std::shared_ptr<StreamBuffer>& output	String buffer used to store the standard output from the MATLAB function.
const std::shared_ptr<StreamBuffer>& error	String buffer used to store error output from the MATLAB function.

Return Value

Zero or one of the following, or a tuple of any combination of them:

A native scalar type

std::vector

matlab::data::Array

Exceptions

matlab::cpplib::CanceledException	The MATLAB function is canceled.
matlab::cpplib::InterruptedException	The MATLAB function is interrupted.
matlab::cpplib::MATLABNotAvailableError	The MATLAB session is not available.
matlab::cpplib::MATLABSyntaxError	The MATLAB function returned a syntax error.
matlab::cpplib::MATLABExecutionError	The function returns a MATLAB Runtime error.
matlab::cpplib::TypeConversionError	The result of a MATLAB function cannot be converted into a user-specific type.

Examples

Execute a User-Written MATLAB Function mysqrt in a C++ Shared Library

// This example assumes that mysqrt is a packaged user-written function that
// calls MATLAB's sqrt, which returns the square root of each element in
// the array that is passed to it.

auto matlabPtr = initMATLABApplication(MATLABApplicationMode::IN_PROCESS, opts);
auto libPtr = initMATLABLibrary(*matlabPtr, u"mylib.ctf");

// Initialize a matlab::data::TypedArray with three elements.
matlab::data::TypedArray<double> doubles = factory.createArray<double>({1.0, 4.0, 9.0});

// Retrieve the result of the mysqrt call. Since the output
// argument is a matlab::data::Array, feval does not require any template
// arguments.
matlab::data::Array mda = libPtr->feval(u"mysqrt", doubles);

// Now we retrieve the first element of that matlab::data::Array.
double d1 = mda[0];
std::assert(d1 == 1.0, "unexpected value");

// Pass a native type (a double) directly to mysqrt. Specify that you want
// a double (rather than a matlab::data::Array) as the return type.
double d2 = libPtr->feval<double>(u"mysqrt", 4.0);
std::assert(d2 == 2.0, "unexpected value");

Version History

Introduced in R2018a