Main Content

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

See Also

| | | | | | |