Create Cell Arrays from C++

A MATLAB^® cell array is a container in which each cell can contain an array of any type. The MATLAB C++ Engine enables you to create cell arrays using the matlab::data::ArrayFactory::createCellArray member function. To create an empty cell array, use createArray<matlab::data::Array>.

These examples show how to pass cell arrays to and from MATLAB. In MATLAB, these arrays are of class cell.

The matlab::data::CellArray class is implemented as an array of arrays defined as:

matlab::data::TypedArray<matlab::data::Array>

For information on how to setup and build C++ engine programs, see Requirements to Build C++ Engine Applications.

Put Cell Array in MATLAB Workspace

This example creates a cell array and puts it in the MATLAB base workspace.

#include "MatlabDataArray.hpp"
#include "MatlabEngine.hpp"

void cellArrayPut() {

    using namespace matlab::engine;

    // Connect to named shared MATLAB session started as:
    // matlab -r "matlab.engine.shareEngine('myMatlabEngine')"
    String session(u"myMatlabEngine");
    std::unique_ptr<MATLABEngine> matlabPtr = connectMATLAB(session);

    // Create MATLAB data array factory
    matlab::data::ArrayFactory factory;

    // Create cell array
    matlab::data::CellArray cellArray1 = factory.createCellArray({ 1,2 },
        factory.createCharArray("MATLAB Cell Array"),
        factory.createArray<double>({ 2,2 }, { 1.2, 2.2, 3.2, 4.2 }));

    // Put cell array in MATLAB workspace
    matlabPtr->setVariable(u"cellArray1", cellArray1);
}

Calling the MATLAB whos function shows the variable in the MATLAB workspace.

>> whos
  Name            Size            Bytes  Class    Attributes

  cellArray1      1x2               290  cell
>> cellArray1{:}

ans =

    'MATLAB Cell Array'


ans =

    1.2000    3.2000
    2.2000    4.2000

Access Elements of Cell Array

Use [] indexing to access the elements of a cell array. For example, access the first element of the cell array created in the previous section and convert the element to a std::string:

matlab::data::CharArray cArray = cellArray1[0][0];
std::string str = cArray.toAscii();

The variable str is a copy of the value in the cell array.

Modify Elements of Cell Array

There are different ways to modify elements in a cell array:

Create a reference to the element and modify the value in the cell array.
Copy the element, change the value, then reassign the value to the cell array.

This example uses matlab::data::TypedArrayRef to create a reference to the array contained in a specific cell. Then the array is modified by changing specific elements in the array using indexed assignment.

#include "MatlabDataArray.hpp"
#include "MatlabEngine.hpp"

void cellArrayMod() {
    //Modify elements of a cell array

    using namespace matlab::engine;

    // Connect to named shared MATLAB session started as:
    // matlab -r "matlab.engine.shareEngine('myMatlabEngine')"
    String session(u"myMatlabEngine");
    std::unique_ptr<MATLABEngine> matlabPtr = connectMATLAB(session);

    // Create MATLAB data array factory
    matlab::data::ArrayFactory factory;

    // Create a 2-by-2 array of arrays   
    matlab::data::CellArray cellArray2 = factory.createArray<matlab::data::Array>({ 2,2 });

    // Assign values to each cell
    cellArray2[0][0] = factory.createCharArray("A cell array");
    cellArray2[0][1] = factory.createArray<double>({ 1,3 }, { 2.2, 3.2, -4.2 });
    cellArray2[1][0] = factory.createArray<bool>({ 1,3 }, { true, true, false });
    cellArray2[1][1] = factory.createScalar<int32_t>(-3374);

    // Get reference to elements of the cell array
    // Modify the elements in the cell array
    matlab::data::TypedArrayRef<double> elem1 = cellArray2[0][1];
    elem1[1] = -3.2;
    matlab::data::TypedArrayRef<bool> elem2 = cellArray2[1][0];
    elem2[1] = false;

    // Put cell array in MATLAB workspace
    matlabPtr->setVariable(u"cellArray2", std::move(cellArray2));
}

The cell array in the MATLAB workspace includes the changes made to the array element references. Here is the cell array in MATLAB.

>> cellArray2{:}

ans =

    'A cell array'


ans =

  1×3 logical array

   1   0   0


ans =

    2.2000   -3.2000   -4.2000


ans =

  int32

   -3374

Get Cell Array from MATLAB

This example gets a cell array from MATLAB. This code assumes that there is a cell array variable named cellArray2 in the MATLAB workspace, like the one created in the previous example. To pass the cell array to MATLAB, see Modify Elements of Cell Array.

To get the cell array, follow these steps:

Use the matlab::engine::MATLABEngine getVariable member function to bring the cell array into C++.
Define the returned cell array as a matlab::data::CellArray.
Return the contents of the cell indexed by [1][0] as a matlab::data::TypedArray<bool>.
Use the TypedArray::getNumberOfElements member function to loop through the elements of the array cell.

void cellArrayGet() {
    using namespace matlab::engine;
    
    // Connect to named shared MATLAB session started as:
    // matlab -r "matlab.engine.shareEngine('myMatlabEngine')"
    String session(u"myMatlabEngine");
    std::unique_ptr<MATLABEngine> matlabPtr = connectMATLAB(session);

    // Get a cell array from MATLAB
    matlab::data::CellArray ca = matlabPtr->getVariable(u"cellArray2");

    // Copy elements of a cell into vector
    matlab::data::TypedArray<bool> const elem2 = ca[1][0];
    std::vector<bool> logicalCell(elem2.getNumberOfElements());
    int i = 0;
    for (auto e : elem2) {
        logicalCell[i] = e;
        ++i;
    }	   
}