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,                          // MATLAB function name as a UTF-16 string
    const matlab::data::Array &arg,                          // Argument to the MATLAB function, as a MATLAB array
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

function name as string

matlab::data::Array feval(
    const std::string &function,                             // MATLAB function name as a UTF-8 string
    const matlab::data::Array &arg,                          // Argument to the MATLAB function, as a MATLAB array
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

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,                          // MATLAB function name as a UTF-16 string
    const std::vector<matlab::data::Array> &args,            // Arguments to the MATLAB function, as a vector of MATLAB arrays
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

function name as string

matlab::data::Array feval(
    const std::string &function,                             // MATLAB function name as a UTF-8 string
    const std::vector<matlab::data::Array> &args,            // Arguments to the MATLAB function, as a vector of MATLAB arrays
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

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,                          // MATLAB function name as a UTF-16 string
    const size_t nlhs,                                       // Number of left-hand-side (output) arguments expected
    const std::vector<matlab::data::Array> &args,            // Arguments to the MATLAB function, as a vector of MATLAB arrays
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

function name as string

std::vector<matlab::data::Array> feval(
    const std::string &function,                             // MATLAB function name as a UTF-8 string
    const size_t nlhs,                                       // Number of left-hand-side (output) arguments expected
    const std::vector<matlab::data::Array> &args,            // Arguments to the MATLAB function, as a vector of MATLAB arrays
    const std::shared_ptr<StreamBuffer> &output = nullptr,   // Optional: Redirect standard output, default is no redirection
    const std::shared_ptr<StreamBuffer> &error = nullptr     // Optional: Redirect standard error, default is no redirection
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

Execute a function with native input and output arguments

function name as u16string

template<class ReturnType, typename... RhsArgs>
ReturnType feval(
    const std::u16string &function,                          // MATLAB function name as a UTF-16 string
    RhsArgs&&... rhsArgs                                     // Arguments to the MATLAB function
);

function name as string

template<class ReturnType, typename... RhsArgs>
ReturnType feval(
    const std::string &function,                             // MATLAB function name as a UTF-8 string
    RhsArgs&&... rhsArgs                                     // Arguments to the MATLAB function
);

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,                          // MATLAB function name as a UTF-16 string
    const std::shared_ptr<StreamBuffer> &output,             // Redirect standard output
    const std::shared_ptr<StreamBuffer> &error,              // Redirect standard error
    RhsArgs&&... rhsArgs                                     // Arguments to the MATLAB function
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

function name as string

template<class ReturnType, typename... RhsArgs>
ReturnType feval(
    const std::string &function,                             // MATLAB function name as a UTF-8 string
    const std::shared_ptr<StreamBuffer> &output,             // Redirect standard output
    const std::shared_ptr<StreamBuffer> &error,              // Redirect standard error
    RhsArgs&&... rhsArgs                                     // Arguments to the MATLAB function
);                                                           // StreamBuffer is std::basic_streambuf<char16_t>

Execute a function with custom C++ structures

ReturnType* output = libPtr->feval<ReturnType*>(
    "functionName",                                         // MATLAB function name as a UTF-8 string
    inputPtr                                                // Pointer to the input arguments
);

The MATLABLibrary::feval function allows you to call a packaged MATLAB function within a C++ shared library by passing the name of the function and its arguments. If the specified function cannot be found in the library, an exception is thrown.

Arguments: You can pass the name of the MATLAB function followed by its arguments, which can include:

Native types
Vectors of native types
MATLAB data arrays
Pointers to user-defined C++ structures when MATLAB Runtime is started in IN_PROCESS mode. For example: For example: UserDefinedStruct*

Return Type: By default, the function returns either:

A single matlab::data::Array object if one output argument is expected.
A std::vector<matlab::data::Array> if zero or multiple output arguments are expected. If a single output is expected and none is returned, the vector is empty.
An alternative return type can be specified using a template argument, which can be:
- A primitive type
- A std::vector of primitive types
- A std::tuple containing multiple instances of these types
- Pointers to user-defined C++ structures. For example: UserDefinedStruct*

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.

Type Conversion

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 MATLAB Function

// 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");

Pass User-Defined C++ Structures to MATLAB Function

Create a custom C++ structure.

namespace mynamespace {
    struct MyStruct {
        std::vector<double> values;
    };
}

Use the custom C++ structure in application code after starting MATLAB Runtime in IN_PROCESS mode.

// Start MATLAB Runtime in IN_PROCESS mode, initialize it, and return an object to it
std::shared_ptr<matlab::cpplib::MATLABApplication> setup() {
    auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
    std::vector<std::u16string> options = { u"-nojvm" };
    std::shared_ptr<matlab::cpplib::MATLABApplication> matlabApplication =
        matlab::cpplib::initMATLABApplication(mode, options);
    return matlabApplication;
}
...
...
...
// Define the MATLAB function name and arguments
std::string functionName = "myMatlabFunction";
mynamespace::MyStruct inputStruct;
inputStruct.values = {1.0, 2.0, 3.0, 4.0, 5.0};
mynamespace::MyStruct* inputPtr = &inputStruct;

// Call the MATLAB function using feval
mynamespace::MyStruct* output = libPtr->feval<mynamespace::MyStruct*>(functionName, inputPtr);

// Use the output (example usage)
if (output) {
    std::cout << "MATLAB function executed successfully." << std::endl;
} else {
    std::cerr << "Failed to execute MATLAB function." << std::endl;
}

Version History

Introduced in R2018a

matlab::cpplib::MATLABLibrary::feval

Description

Parameters

Return Value

Exceptions

Examples

Execute MATLAB Function

Pass User-Defined C++ Structures to MATLAB Function

Version History

See Also