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:
|
RhsArgs | A sequence of zero or more arguments which are one of the following:
|
StreamBuffer |
|
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>
whereT
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
| 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:
|
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
See Also
matlab::cpplib::convertUTF8StringToUTF16String
| matlab::cpplib::convertUTF16StringToUTF8String
| matlab::cpplib::initMATLABApplication
| matlab::cpplib::runMain
| matlab::cpplib::initMATLABLibrary
| matlab::cpplib::initMATLABLibraryAsync
| matlab::cpplib::MATLABLibrary::fevalAsync
| matlab::cpplib::MATLABLibrary::waitForFiguresToClose