matlab::engine::MATLABEngine

R2026b

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

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.

Syntax

Execute a function and return multiple results.

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

Execute a function with multiple inputs and return a single result.

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

Execute a function with a single input and return a single result.

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

Execute a function with native C++ types and redirect output streams.

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)

Execute a function with native C++ types.

ResultType feval(const matlab::engine::String &function,
   RhsArgs&&... rhsArgs)

Execute a function with custom C++ structure input and return a custom C++ structure. (since R2026b)

ResultType* outStructPtr = matlabPtr->feval<ResultType*>(const matlab::engine::String &function,inStructPtr)

For more details, see Pass C++ Structures to MATLAB Functions.

Parameters

const matlab::engine::String &function

Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string or 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. For an example, see Pass Stream Buffer Type for Standard Output or Error.

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. For an example, see Pass Stream Buffer Type for Standard Output or Error.

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)

matlab::data::Array data types:

(since R2026a)

inStructPtr

outStructPtr

Pointers to custom C++ structures used as function inputs (inStructPtr) and outputs (outStructPtr). To pass custom C++ structures to and from MATLAB, you must start MATLAB using IN_PROCESS mode. For more information, see Pass C++ Structures to MATLAB Functions. (since R2026b)

Return Value

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

Multiple outputs returned from the MATLAB function

matlab::data::Array

Single output returned from the MATLAB function.

ResultType

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

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 matlab::data::Array with the dimensions 2-by-3 from a vector of numeric values of type double.

  • Start a shared MATLAB session.

  • Pass the data array to the MATLAB sqrt function and return 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.

You can pass custom C++ structure pointers to feval after associating the structure type with a MATLAB interface to a C++ library using the USING_TYPE_WITH_MATLAB macro. For example, this code passes two Position structure pointers to a MATLAB function and receives a Rectangle structure pointer as output.

#include "MatlabEngine.hpp"
#include "shapes.hpp"

USING_TYPE_WITH_MATLAB(Shapes::Position, "ShapesLib");
USING_TYPE_WITH_MATLAB(Shapes::Rectangle, "ShapesLib");

using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(MATLABApplicationMode::IN_PROCESS);

Shapes::Position p1{0, 0}, p2{10, 5};
Shapes::Rectangle* rectPtr = matlabPtr->feval<Shapes::Rectangle*>(u"createRectangle", &p1, &p2);
    ...
delete rectPtr;
For a complete example, see Pass C++ Structures to MATLAB Functions. (since R2026b)

fevalAsync

Evaluate MATLAB functions with input arguments and returned values asynchronously.

Syntax

Execute a function asynchronously and return multiple results.

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

Execute a function asynchronously with multiple inputs and return a single result.

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

Execute a function asynchronously with a single input and return a single result.

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

Execute a function asynchronously with native C++ types and redirect output streams.

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)

Execute a function asynchronously with native C++ types.

FutureResult<ResultType> fevalAsync(const matlab::engine::String &function,
   RhsArgs&&... rhsArgs)

Execute a function with custom C++ structure input and return a custom C++ structure. (since R2026b)

FutureResult<ResultType*> future = matlabPtr->fevalAsync<ResultType*>(const matlab::engine::String &function,inStructPtr)

For more details, see Pass C++ Structures to MATLAB Functions.

Parameters

const matlab::engine::String &function

Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string or 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. For an example, see Pass Stream Buffer Type for Standard Output or Error.

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. For an example, see Pass Stream Buffer Type for Standard Output or Error.

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)

matlab::data::Array (since R2024a)

matlab::data::Array data types:

(since R2026a)

inStructPtr

Pointers to custom C++ structures used as function inputs (inStructPtr). If the function returns a custom C++ structure, it is returned through the FutureResult object. To pass custom C++ structures to and from MATLAB, you must start MATLAB using IN_PROCESS mode. For more information, see Pass C++ Structures to MATLAB Functions. (since R2026b)

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

You can pass custom C++ structure pointers to fevalAsync after associating the structure type with a MATLAB interface to a C++ library using the USING_TYPE_WITH_MATLAB macro. For example, this code passes two Position structure pointers to a MATLAB function asynchronously and receives a Rectangle structure pointer as output.

#include "MatlabEngine.hpp"
#include "shapes.hpp"

USING_TYPE_WITH_MATLAB(Shapes::Position, "ShapesLib");
USING_TYPE_WITH_MATLAB(Shapes::Rectangle, "ShapesLib");

using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(MATLABApplicationMode::IN_PROCESS);

Shapes::Position p1{0, 0}, p2{10, 5};
FutureResult<Shapes::Rectangle*> future = matlabPtr->fevalAsync<Shapes::Rectangle*>(u"createRectangle", &p1, &p2);
    ...
Shapes::Rectangle* rectPtr = future.get();
    ...
delete rectPtr;
For a complete example, see Pass C++ Structures to MATLAB Functions. (since R2026b)

eval

Evaluate a MATLAB statement as a string synchronously.

Syntax
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> ())
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. For an example, see Redirect Screen Output.

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

Stream buffer used to store the error message from the MATLAB command. For an example, see Redirect Error Output.

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

Evaluate a MATLAB statement as a string asynchronously.

Syntax
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> ())
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. For an example, see Redirect Screen Output.

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

Stream buffer used to store the error message from the MATLAB command. For an example, see Redirect Error Output.

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

Get a variable from the MATLAB base or global workspace.

Syntax
matlab::data::Array getVariable(const matlab::engine::String &varName,
    matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
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

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

Syntax
FutureResult<matlab::data::Array> getVariableAsync(const matlab::engine::String &varName,
    matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
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

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.

Syntax
void setVariable(const matlab::engine::String &varName,
   const matlab::data::Array &var,
   matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
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

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.

Syntax
FutureResult<void> setVariableAsync(const matlab::engine::String &varName,
   const matlab::data::Array var,
   matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)
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

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.

Syntax

Get a property value from an element of an object array

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName)

Get a property value from a scalar object

matlab::data::Array getProperty(const matlab::data::Array &object,
   const matlab::engine::String &propertyName)
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

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.

Syntax

Get a property value asynchronously from an element of an object array

FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName)

Get a property value asynchronously from a scalar object

FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const matlab::engine::String &propertyName)
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

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.

Syntax

Set a property value on an element of an object array

void setProperty(matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)

Set a property value on a scalar object

void setProperty(matlab::data::Array &object,
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)
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

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.

Syntax

Set a property value asynchronously on an element of an object array

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)

Set a property value asynchronously on a scalar object

FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const matlab::engine::String &propertyName,
 const matlab::data::Array &propertyValue)
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