Main Content

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

Member Functions

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

Evaluate MATLAB functions with input arguments synchronously. Use feval to pass arguments from C++ to MATLAB and to return a result from MATLAB to C++.

Inputs and outputs can be types defined by the MATLAB Data API or can be native C++ types.

Parameters

const matlab::engine::String &function

Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const size_t numReturned

Number of returned values

const std::vector<matlab::data::Array> &args

Multiple input arguments to pass to the MATLAB function in an std::vector. The vector is converted to a column array in MATLAB.

const matlab::data::Array arg

Single input argument to pass to the MATLAB function.

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

Stream buffer used to store the standard output from the MATLAB function.

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

Stream buffer used to store the error message from the MATLAB function.

RhsArgs&&... rhsArgs

Native C++ data types:

  • std::float

  • std::double

  • std::int8_t, std::uint8_t

  • std::int16_t, std::uint16_t

  • std::int32_t, std::uint32_t

  • std::int64_t, std::uint64_t

  • std::bool

  • std::string, std::u16string (since R2024a)

std::vector data types:

  • std::vector<float>

  • std::vector<double>

  • std::vector<int8_t>, std::vector<uint8_t>

  • std::vector<int16_t>, std::vector<uint16_t>

  • std::vector<int32_t>, std::vector<uint32_t>

  • std::vector<int64_t>, std::vector<uint64_t>

(since R2024a)

std::complex data types:

  • std::complex<float>

  • std::complex<double>

  • std::complex<int8_t>, std::complex<uint8_t>

  • std::complex<int16_t>, std::complex<uint16_t>

  • std::complex<int32_t>, std::complex<uint32_t>

  • std::complex<int64_t>, std::complex<uint64_t>

(since R2024a)

Return Value

std::vector<matlab::data::Array>

Outputs returned from MATLAB function.

matlab::data::Array

Single output returned from MATLAB function.

ResultType

Output returned from MATLAB function as a user-specified type. Can be an std::tuple if returning multiple arguments.

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

matlab::engine::MATLABExecutionException

There is a MATLAB run-time error in the function.

matlab::engine::TypeConversionException

The result of a MATLAB function cannot be converted to the specified type.

matlab::engine::MATLABSyntaxException

There is a syntax error in the MATLAB function.

Examples

This example passes an array of numeric values to a MATLAB function. The code performs these steps:

  • Creates a matlab::data::Array with 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 sqrt function 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)
Description

Evaluate MATLAB functions with input arguments and returned values asynchronously.

Parameters

const matlab::engine::String &function

Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const size_t numReturned

Number of returned values

const std::vector<matlab::data::Array> &args

Multiple input arguments to pass to the MATLAB function in an std::vector. The vector is converted to a column array in MATLAB.

const matlab::data::Array arg

Single input argument to pass to the MATLAB function.

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

Stream buffer used to store the standard output from the MATLAB function.

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

Stream buffer used to store the error message from the MATLAB function.

RhsArgs&&... rhsArgs

Native C++ data types:

  • std::float

  • std::double

  • std::int8_t, std::uint8_t

  • std::int16_t, std::uint16_t

  • std::int32_t, std::uint32_t

  • std::int64_t, std::uint64_t

  • std::bool

  • std::string, std::u16string (since R2024a)

std::vector data types:

  • std::vector<float>

  • std::vector<double>

  • std::vector<int8_t>, std::vector<uint8_t>

  • std::vector<int16_t>, std::vector<uint16_t>

  • std::vector<int32_t>, std::vector<uint32_t>

  • std::vector<int64_t>, std::vector<uint64_t>

(since R2024a)

std::complex data types:

  • std::complex<float>

  • std::complex<double>

  • std::complex<int8_t>, std::complex<uint8_t>

  • std::complex<int16_t>, std::complex<uint16_t>

  • std::complex<int32_t>, std::complex<uint32_t>

  • std::complex<int64_t>, std::complex<uint64_t>

(since R2024a)

Return Value

FutureResult

A FutureResult object used to get the result of calling the MATLAB function.

Exceptions

None

Examples

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> ())
Description

Evaluate a MATLAB statement as a string synchronously.

Parameters

const matlab::engine::String &statement

MATLAB statement to evaluate

const std::shared_ptr<matlab::engine::StreamBuffer> &output

Stream buffer used to store the standard output from the MATLAB statement.

const std::shared_ptr<matlab::engine::StreamBuffer> &error

Stream buffer used to store the error message from the MATLAB command.

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

matlab::engine::MATLABExecutionException

There is a run-time error in the MATLAB statement.

matlab::engine::MATLABSyntaxException

There is a syntax error in the MATLAB statement.

Examples

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> ())
Description

Evaluate a MATLAB statement as a string asynchronously.

Parameters

const matlab::engine::String& str

MATLAB statement to evaluate

const std::shared_ptr<matlab::engine::StreamBuffer> & output

Stream buffer used to store the standard output from the MATLAB statement.

const std::shared_ptr<matlab::engine::StreamBuffer> & error

Stream buffer used to store the error message from the MATLAB command.

Return Value

FutureResult

A FutureResult object used to wait for the completion of the MATLAB statement.

Exceptions

None

Examples

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

Get a variable from the MATLAB base or global workspace.

Parameters

const matlab::engine::String& varName

Name of a variable in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

MATLAB workspace (BASE or GLOBAL) to get the variable from. For more information, see global.

Return Value

matlab::data::Array

Variable obtained from the MATLAB base or global workspace

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

matlab::engine::MATLABExecutionException

The requested variable does not exist in the specified MATLAB base or global workspace.

Examples

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

Get a variable from the MATLAB base or global workspace asynchronously.

Parameters

const matlab::engine::String& varName

Name of the variable in MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

MATLAB workspace (BASE or GLOBAL) to get the variable from. For more information, see global.

Return Value

FutureResult

A FutureResult object that you can use to get the variable obtained from the MATLAB workspace as a matlab.data.Array.

Exceptions

None

Examples

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

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.

Parameters

const matlab::engine::String& varName

Name of the variable to create in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const matlab::data::Array var

Value of the variable to create in the MATLAB workspace

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

Put the variable in the MATLAB BASE or GLOBAL workspace. For more information, see global.

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

Examples

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

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.

Parameters

const matlab::engine::String& varName

Name of the variable to create in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const matlab::data::Array var

Value of the variable to create in the MATLAB workspace

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

Put the variable in the MATLAB BASE or GLOBAL workspace. For more information, see global.

Exceptions

None

Example

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

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.

Parameters

const matlab::data::Array &objectArray

Array of MATLAB objects

const matlab::data::Array &object

Scalar MATLAB object

size_t index

Zero-based index into the object array, specifying the object in that array whose property value is returned

const String &propertyName

Name of the property. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

Return Value

matlab::data::Array

Value of the named property

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

matlab::engine::MATLABExecutionException

The property does not exist.

Examples

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

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.

Parameters

const matlab::data::Array &objectArray

Array of MATLAB objects

const matlab::data::Array &object

Scalar MATLAB object

size_t index

Zero-based index into the object array, specifying the object in that array whose property value is returned

const matlab::engine::String &propertyName

Name of the property. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

Return Value

FutureResult

FutureResult object that is used to synchronize the operation.

Exceptions

None

Examples

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

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.

Parameters

matlab::data::Array &objectArray

Array of MATLAB objects

matlab::data::Array &object

Scalar MATLAB object

size_t index

Zero-based index into the object array, specifying the object in that array whose property value is set

const matlab::engine::String &propertyName

Name of the property to set. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const matlab::data::Array &propertyValue

Value assigned to the property

Exceptions

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available.

matlab::engine::MATLABExecutionException

The property does not exist.

Examples

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

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.

Parameters

matlab::data::Array &objectArray

Array of MATLAB objects

matlab::data::Array &object

Scalar MATLAB object

size_t index

Zero-based index into the object array, specifying the object in that array whose property value is set

const matlab::engine::String &propertyName

Name of the property to set. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

const matlab::data::Array &propertyValue

Value assigned to the property.

Exceptions

None

Examples

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

Version History

Introduced in R2017b

expand all