matlab::cpplib::MATLAB 库::feval

从可部署存档中执行 MATLAB 函数

描述

执行具有 1 个输出 MATLAB^® 数据数组参量的函数；1 个输入 MATLAB 数据数组参量

函数名称为 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>

函数名称作为字符串

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>

执行具有 1 个输出 MATLAB 数据数组参量的函数；0、2 个或更多输入 MATLAB 数据数组参量

函数名称为 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>

函数名称作为字符串

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>

执行具有 0、2 或更多输出 MATLAB 数据数组参量的函数；任意数量的输入 MATLAB 数据数组参量

函数名称为 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>

函数名称作为字符串

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>

使用本机输入和输出参量执行函数

函数名称为 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
);

函数名称作为字符串

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

使用本机输入和输出参量执行函数，并进行输出重定向

函数名称为 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>

函数名称作为字符串

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>

使用自定义 C++ 结构执行函数

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

MATLABLibrary::feval 函数允许您通过传递函数名称及其参量来调用 C++ 共享库中打包的 MATLAB 函数。如果在库中找不到指定的函数，则会引发异常。

参量：您可以传递 MATLAB 函数的名称及其参量，其中可以包括：

本机类型
原生类型的向量
MATLAB 数据数组
当 MATLAB Runtime 以 IN_PROCESS 模式启动时，指向用户定义的 C++ 结构的指针。例如：例如：UserDefinedStruct*

返回类型：默认情况下，该函数返回：

如果需要一个输出参量，则为单个 matlab::data::Array 对象。
如果需要零个或多个输出参量，std::vector<matlab::data::Array>。如果预期只有一个输出但未返回任何输出，则向量为空。
可以使用模板参量指定替代返回类型，可以是：
- 原始类型
- 原始类型的 std::vector
- 包含这些类型的多个实例的 std::tuple
- 指向用户定义的 C++ 结构的指针。例如：UserDefinedStruct*

支持的本机类型

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> 其中 T 是数值类型之一。

类型转换

作为输入传递的本机 C++ 数据被转换为相应的 MATLAB 类型。
std::vector 在 MATLAB 中转换为列数组。
如果没有范围损失，则 MATLAB 函数的结果将转换为预期的 C++ 数据类型；否则，将引发异常。

参数

`const std::u16string &function` `const std::string &function`	要评估的已编译 MATLAB 函数的名称，指定为 `u16string` 或 `string`。
`const size_t nlhs`	返回值的数量。
`const std::vector<matlab::data::Array>& args`	当指定多个时，MATLAB 函数使用的参量。
`const matlab::data::Array>& arg`	具有单一输入的 MATLAB 函数使用的参量。
`const RhsArgs& rhsArgs`	模板参数包由零个或多个参量的序列组成，每个参数都是下列之一：裸本机类型（请参阅支持的本机类型列表）裸本机类型的 `std::vector` `matlab::data::Array`
`const std::shared_ptr<StreamBuffer>& output`	用于存储 MATLAB 函数标准输出的字符串缓冲区。
`const std::shared_ptr<StreamBuffer>& error`	用于存储 MATLAB 函数的错误输出的字符串缓冲区。

返回值

以下零个或一个，或者它们的任意组合的元组：

本机标量类型

std::vector

matlab::data::Array

异常

`matlab::cpplib::CanceledException`	MATLAB 函数被取消。
`matlab::cpplib::InterruptedException`	MATLAB 函数被中断。
`matlab::cpplib::MATLABNotAvailableError`	MATLAB 会话不可用。
`matlab::cpplib::MATLABSyntaxError`	MATLAB 函数返回了语法错误。
`matlab::cpplib::MATLABExecutionError`	该函数返回 MATLAB Runtime 错误。
`matlab::cpplib::TypeConversionError`	MATLAB 函数的结果不能转换为用户特定的类型。

示例

执行 MATLAB 函数

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

将用户定义的 C++ 结构传递给 MATLAB 函数

创建自定义 C++ 结构。

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

在 IN_PROCESS 模式下启动 MATLAB Runtime 后，在应用程序代码中使用自定义 C++ 结构。

// 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;
}

版本历史记录

在 R2018a 中推出

另请参阅

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