matlab::engine::MATLABEngine
Evaluate MATLAB functions from C++ program
Description
The matlab::engine::MATLABEngine class uses a MATLAB® process as a computational engine for C++. This class provides an interface
between the C++ language and MATLAB, enabling you to evaluate MATLAB functions and expressions from C++ programs.
Class Details
|
Namespace: | matlab::engine |
| Include: | MatlabEngine.hpp |
Factory Methods
The matlab::engine::MATLABEngine class provides methods to start
MATLAB and to connect to a shared MATLAB session synchronously or asynchronously.
matlab::engine::startMATLAB— Start MATLAB synchronouslymatlab::engine::startMATLABAsync— Start MATLAB asynchronouslymatlab::engine::connectMATLAB— Connect to shared MATLAB session synchronouslymatlab::engine::connectMATLABAsync— Connect to shared MATLAB session asynchronously
Unsupported Startup Options
The engine does not support these MATLAB startup options:
-h-help-?-n-e-softwareopengl-logfile
For information on MATLAB startup options, see Commonly Used Startup Options. For an example of how to use MATLAB startup options when starting engine applications, see Start MATLAB with Startup Options.
Method Summary
Member Functions
|
Evaluate MATLAB function with arguments synchronously | |
|
Evaluate MATLAB function with arguments asynchronously | |
|
Evaluate MATLAB statement as a string synchronously | |
|
Evaluate MATLAB statement as a string asynchronously | |
|
Get variable from the MATLAB base workspace synchronously | |
|
Get variable from the MATLAB base workspace asynchronously | |
|
Put variable into the MATLAB base workspace synchronously | |
|
Put variable into the MATLAB base workspace asynchronously | |
|
Get object property value | |
|
Get object property value asynchronously | |
|
Set object property value | |
|
Set object property value asynchronously |
Member Function Details
feval
std::vector<matlab::data::Array> feval(const matlab::engine::String &function, const size_t numReturned, const std::vector<matlab::data::Array> &args, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const matlab::engine::String &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const matlab::engine::String &function, const matlab::data::Array &arg, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
ResultType feval(const matlab::engine::String &function, const std::shared_ptr<matlab::engine::StreamBuffer> &output, const std::shared_ptr<matlab::engine::StreamBuffer> &error, RhsArgs&&... rhsArgs )
ResultType feval(const matlab::engine::String &function, RhsArgs&&... rhsArgs)
Evaluate MATLAB functions with input arguments synchronously. Use feval when you want to pass arguments from C++ to MATLAB and when you want to return a result from MATLAB to C++.
Inputs and outputs can be types defined by the MATLAB Data Array API or can be native C++ types.
|
| Name of the MATLAB function or script to evaluate. Specify the
name as an |
|
|
Number of returned values |
|
| Multiple input arguments to pass to the MATLAB function in an |
|
|
Single input argument to pass to the MATLAB function. |
|
|
Stream buffer used to store the standard output from the MATLAB function. |
|
|
Stream buffer used to store the error message from the MATLAB function. |
|
|
Native C++ data types used for function inputs.
|
|
|
Outputs returned from MATLAB function. |
|
|
Single output returned from MATLAB function. |
|
| Output returned from MATLAB function as a user-specified type. Can be an
|
|
|
The MATLAB session is not available. |
|
|
There is a MATLAB runtime error in the function. |
|
|
The result of a MATLAB function cannot be converted to the specified type. |
|
|
There is a syntax error in the MATLAB function. |
This example passes an array of numeric values to a MATLAB function. The code performs these steps:
Creates a
matlab::data::Arraywith the dimensions 2-by-3 from a vector of numeric values of type double.Starts a shared MATLAB session.
Passes the data array to the MATLAB
sqrtfunction and returns the result to C++.
#include "MatlabDataArray.hpp" #include "MatlabEngine.hpp" using namespace matlab::engine;
std::vector<double> cppData{ 4, 8, 12, 16, 20, 24 };
// Create a 2-by-3 matlab data array
matlab::data::ArrayFactory factory;
auto inputArray = factory.createArray({ 2, 3 }, cppData.cbegin(), cppData.cend());
// Start MATLAB engine
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
// Pass data array to MATLAB sqrt function
// And return results.
auto result = matlabPtr->feval(u"sqrt", inputArray);When calling feval using native C++ types, the input
arguments are restricted to scalar values. For example, this code returns the
square root of a scalar value.
#include "MatlabEngine.hpp" using namespace matlab::engine;
// Start MATLAB engine synchronously
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
// Call sqrt function
double result = matlabPtr->feval<double>(u"sqrt", double(27));For functions that return multiple output arguments, you can use the
MATLAB data API or, if using C++ types, an std::tuple.
For an example, see Call Function with Native C++ Types.
fevalAsync
FutureResult<std::vector<matlab::data::Array>> fevalAsync(const matlab::engine::String &function, const size_t numReturned, const std::vector<matlab::data::Array> &args, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const matlab::engine::String &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const matlab::engine::String &function, const matlab::data::Array &arg, const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(), const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<ResultType> fevalAsync(const matlab::engine::String &function, const std::shared_ptr<matlab::engine::StreamBuffer> &output, const std::shared_ptr<matlab::engine::StreamBuffer> &error, RhsArgs&&... rhsArgs)
FutureResult<ResultType> fevalAsync(const matlab::engine::String &function, RhsArgs&&... rhsArgs)
Evaluate MATLAB function with input arguments and returned values asynchronously.
|
| Name of the MATLAB function or script to evaluate. Specify the
name as an |
|
|
Number of returned values |
|
| Multiple input arguments to pass to the MATLAB function in an |
|
|
Single input argument to pass to the MATLAB function. |
|
|
Stream buffer used to store the standard output from the MATLAB function. |
|
|
Stream buffer used to store the error message from the MATLAB function. |
|
|
Native C++ data types used for function inputs.
|
|
|
A |
None
This example passes the scalar double 12.7 to the MATLAB
sqrt function asynchronously. The
FutureResult is then used to get the result.
#include "MatlabDataArray.hpp" #include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::ArrayFactory factory;
matlab::data::Array argument = factory.createScalar<double>(12.7);
FutureResult<matlab::data::Array> future = matlabPtr->fevalAsync(u"sqrt", std::move(argument));
...
matlab::data::TypedArray<double> result = future.get();eval
void eval(const matlab::engine::String &statement, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())
Evaluate a MATLAB statement as a string synchronously.
|
|
MATLAB statement to evaluate |
|
|
Stream buffer used to store the standard output from the MATLAB statement. |
|
|
Stream buffer used to store the error message from the MATLAB command. |
|
|
The MATLAB session is not available. |
|
|
There is a runtime error in the MATLAB statement. |
|
|
There is a syntax error in the MATLAB statement. |
This example evaluates the following MATLAB statement.
a = sqrt(12.7);
The statement creates the variable a in the MATLAB base workspace.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); matlabPtr->eval(u"a = sqrt(12.7);");
evalAsync
FutureResult<void> evalAsync(const matlab::engine::String &str, const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (), const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())
Evaluate a MATLAB statement as a string asynchronously.
|
MATLAB statement to evaluate |
|
|
Stream buffer used to store the standard output from the MATLAB statement. |
|
|
Stream buffer used to store the error message from the MATLAB command. |
|
|
A |
None
This example evaluates the following MATLAB statement asynchronously.
a = sqrt(12.7);
The statement creates the variable a in the MATLAB base workspace.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); FutureResult<void> future = matlabPtr->evalAsync(u"a = sqrt(12.7);");
getVariable
matlab::data::Array getVariable(const matlab::engine::String &varName,
matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)Get a variable from the MATLAB base or global workspace.
|
| Name of a variable in the MATLAB workspace. Specify the name as an
|
|
MATLAB workspace (BASE or GLOBAL) to get the variable
from. For more information, see |
|
|
Variable obtained from the MATLAB base or global workspace |
|
|
The MATLAB session is not available. |
|
|
The requested variable does not exist in the specified MATLAB base or global workspace. |
This example gets a variable named varName from the MATLAB base workspace.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); matlab::data::Array varName = matlabPtr->getVariable(u"varName");
getVariableAsync
FutureResult<matlab::data::Array> getVariableAsync(const matlab::engine::String &varName,
matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)Get a variable from the MATLAB base or global workspace asynchronously.
|
| Name of the variable in MATLAB workspace. Specify the name as an
|
|
MATLAB workspace (BASE or GLOBAL) to get the variable
from. For more information, see |
|
|
A |
None
This example gets a variable named varName from the MATLAB base workspace asynchronously.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); FutureResult<matlab::data::Array> future = matlabPtr->getVariableAsync(u"varName"); ... matlab::data::Array varName = future.get();
setVariable
void setVariable(const matlab::engine::String &varName, const matlab::data::Array &var, matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
Put a variable into the MATLAB base or global workspace. If a variable with the same name exists in
the MATLAB workspace, setVariable overwrites it.
|
| Name of the variable to create in the MATLAB workspace. Specify the name as an
|
|
|
Value of the variable to create in the MATLAB workspace |
|
Put the variable in the MATLAB BASE or GLOBAL workspace. For more
information, see |
|
|
The MATLAB session is not available. |
This example puts the variable named data in the MATLAB base workspace.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::Array data = factory.createArray<double>({ 1, 3 }, { 4, 8, 6 });
matlabPtr->setVariable(u"data", data);setVariableAsync
FutureResult<void> setVariableAsync(const matlab::engine::String &varName, const matlab::data::Array var, matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
Put a variable into the MATLAB base or global workspace asynchronously. If a variable with the same
name exists in the MATLAB base workspace, setVariableAsync overwrites
it.
|
| Name of the variable to create in the MATLAB workspace. Specify the name as an
|
|
|
Value of the variable to create in the MATLAB workspace |
|
Put the variable in the MATLAB BASE or GLOBAL workspace. For more
information, see |
None
This example puts the variable named data in the MATLAB base workspace.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::Array data = factory.createArray<double>({ 1, 3 }, { 4., 8., 6. });
FutureResult<void> future = matlabPtr->setVariableAsync(u"data", data);getProperty
matlab::data::Array getProperty(const matlab::data::Array &objectArray,
size_t index,
const matlab::engine::String &propertyName)matlab::data::Array getProperty(const matlab::data::Array &object, const matlab::engine::String &propertyName)
Get the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.
| Array of MATLAB objects |
|
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is returned |
|
| Name of the property. Specify the name as an
|
|
|
Value of the named property |
|
|
The MATLAB session is not available. |
|
|
The property does not exist. |
This example evaluates a MATLAB statement in a try/catch block using
MATLABEngine::eval. The
MATLABEngine::getVariable member function returns the exception
object. MATLABEngine::getProperty returns the exception
message property value as a
matlab::data::CharArray.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); matlabPtr->eval(u"try; surf(4); catch me; end"); matlab::data::Array mException = matlabPtr->getVariable(u"me"); matlab::data::CharArray message = matlabPtr->getProperty(mException, u"message"); std::cout << "messages is: " << message.toAscii() << std::endl;
getPropertyAsync
FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
size_t index,
const matlab::engine::String &propertyName)FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object, const matlab::engine::String &propertyName)
Get the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.
| Array of MATLAB objects |
|
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is returned |
| Name of the property. Specify the name as an
|
|
|
|
None
This example evaluates a MATLAB statement in a try/catch block using
MATLABEngine::eval. The
MATLABEngine::getVariable member function returns the exception
object. MATLABEngine::getPropertyAsync returns a
FutureResult that you use to get the exception
message property value as a
matlab::data::CharArray.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(); matlabPtr->eval(u"try;surf(4);catch me;end"); matlab::data::Array mException = matlabPtr->getVariable(u"me"); FutureResult<matlab::data::Array> future = matlabPtr->getPropertyAsync(mException, u"message"); matlab::data::CharArray message = future.get(); std::cout << "messages is: " << message.toAscii() << std::endl;
setProperty
void setProperty(matlab::data::Array &objectArray,
size_t index,
const matlab::engine::String &propertyName,
const matlab::data::Array &propertyValue)void setProperty(matlab::data::Array &object,
const matlab::engine::String &propertyName,
const matlab::data::Array &propertyValue)Set the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.
| Array of MATLAB objects |
|
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is set |
| Name of the property to set. Specify the name as an
|
const matlab::data::Array
&propertyValue |
Value assigned to the property |
|
|
The MATLAB session is not available. |
|
|
The property does not exist. |
This example shows how to set a MATLAB object property. It creates a MATLAB graph and returns the line handle object. Setting the value of the
line LineStyle property to the character :
changes the property value of the line object in MATLAB and updates the line style of the graph.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::ArrayFactory factory;
matlab::data::Array yData = factory.createArray<double>({ 1, 5 }, { 4.0, 11.0, 4.7, 36.2, 72.3 });
matlab::data::Array lineHandle = matlabPtr->feval(u"plot", yData);
matlab::data::CharArray lineStyle = factory.createCharArray(":");
matlabPtr->setProperty(lineHandle, u"LineStyle", lineStyle);setPropertyAsync
FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,
size_t index,
const matlab::engine::String &propertyName,
const matlab::data::Array &propertyValue)FutureResult<void> setPropertyAsync(matlab::data::Array &object, const matlab::engine::String &propertyName, const matlab::data::Array &propertyValue)
Set the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.
| Array of MATLAB objects |
|
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is set |
| Name of the property to set. Specify the name as an
|
const matlab::data::Array
&propertyValue |
Value assigned to the property. |
None
This example shows how to set a MATLAB object property asynchronously. It creates a MATLAB graph and returns the line handle object. Setting the line
LineStyle property to the character :
changes the property value of the object in MATLAB and updates the line style of the graph.
#include "MatlabEngine.hpp" using namespace matlab::engine;
std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::ArrayFactory factory;
matlab::data::Array yData = factory.createArray<double>({ 1, 5 }, { 4.0, 11.0, 4.7, 36.2, 72.3 });
matlab::data::Array lineHandle = matlabPtr->feval(u"plot", yData);
matlab::data::CharArray lineStyle = factory.createCharArray(":");
FutureResult<void> future = matlabPtr->setPropertyAsync(lineHandle, u"LineStyle", lineStyle);
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
