Documentation

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 Arrray 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

LhsItemOne 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 nlhsThe number of return values.
const std::vector<matlab::data::Array>& argsArguments used by the MATLAB function when more than one is specified.
const matlab::data::Array>& argArgument 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>& outputString buffer used to store the standard output from the MATLAB function.
const std::shared_ptr<StreamBuffer>& errorString 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");

Introduced in R2018a