Using the C++ Math Library

Creating Cell Arrays

The MATLAB C++ Math Library allows you to create cell arrays by:

• Using a cell array creation function
• Using a cell array conversion function
• Concatenating existing arrays
• Assigning a value to an element in a cell array

Using a Cell Array Creation Routine

Using the MATLAB C++ Math Library cell() routine, you can create a cell array of any size and dimension. You specify the size of each dimension as arguments to the routine. The cell() routine creates an array of empty cells. The following code fragment creates a 2-by-3-by-2 cell array. If you specify a single argument, MATLAB creates a square matrix.

mwArray  C;

C = cell(2,3,2);

cout << C << endl;

This code produces the following output:

(:,:,1) =
    []   []   []
    []   []   []
(:,:,2) =
    []   []   []
    []   []   []

Using a Cell Array Conversion Routines

You can also create cell arrays by converting other MATLAB arrays into cell arrays. The MATLAB C++ Math Library includes routines that convert a numeric array into a cell array, num2cell(), or a structure into a cell array, struct2cell().

The following code fragment creates a numeric array, using ones(), and converts it into a cell array using the num2cell() routine.

mwArray B = ones(2,3);

cout << "B" << B << endl; 

mwArray C = num2cell(B);

cout << "C" << C << endl;

In this output, the brackets indicate that each element in the numeric array has been placed into a cell in the cell array.

B  [ 
    1     1     1;
    1     1     1
  ]

C   [1]  [1]  [1]
    [1]  [1]  [1]

The brackets indicate cell array elements.

Creating Cell Arrays through Concatenation

In MATLAB, you can create a cell array by combining groups of arrays together using the MATLAB cell concatenation operator: curly braces ({}). For example, the following MATLAB statement horizontally concatenates several individual arrays into a 1-by-4 array of cells.

C = { 'jon' ones(2) magic(3) 5 }

C = 
    'jon'    [2x2 double]    [3x3 double]    [5]

To create a cell array with multiple rows in MATLAB, use the same syntax, inserting semicolons into the list of arrays at row breaks.

The MATLAB C++ Math Library uses the cellhcat() routine to emulate the MATLAB {} operator. For example, the following code fragment creates the same 1-by-4 cell array.

mwArray C;

C = cellhcat( "jon", ones(2), magic(3), 5 );

cout << "C = \n" << C << endl;

This code produces the following cell array:

C = 
    'jon'    [2x2 double]    [3x3 double]    [5]

To create a cell array with multiple rows, you must use cellhcat() to create the horizontal rows and vertcat() to stack the rows in columns.

mwArray C;

C = vertcat(cellhcat("jon",ones(2)),cellhcat(magic(3), 5 ));

cout << "C = \n" << C << endl;

This code produces the following two-dimensional cell array:

C = 
    'jon'           [2x2 double]
    [3x3 double]    [         5]

Creating Multidimensional Cell Arrays by Concatenation.   

To create a cell array of more than two dimensions, you must concatenate several existing cell arrays using the cat() routine. The cat() routine uses the following syntax

B = cat(dim,A1,A2...)

where A1, A2, and so on are the cell arrays to concatenate, and dim is the dimension along which to concatenate them.

For example, the following code fragment creates a pair of two-dimensional cell arrays and then uses cat() to concatenate them along three-dimensions to create a 2-by-2-by-2 cell array.

mwArray C = vertcat( cellhcat("jon",5),
                     cellhcat(magic(3),ones(2)));

mwArray D = vertcat( cellhcat("jim",zeros(3)),
                     cellhcat("joe",12));

mwArray E = cat( 3, C, D);
cout << E << endl;

This code produces the following output:

(:,:,1) 
    'jon'           [         5]
    [3x3 double]    [2x2 double]
(:,:,2) 
    'jim'           [3x3 double]
    'joe'           [        12]

Creating Cell Arrays by Assignment

When you assign a value to an element in a cell array, the MATLAB C++ Math Library creates the array (or extends an existing array) to accommodate the assignment. For cell arrays, the library supports two ways to perform this assignment:

• Cell indexing
• Content indexing

With cell indexing, you identify the target location of the assignment (the left hand side of the assignment statement) using standard MATLAB indexing syntax, and you enclose the values to be assigned to the cell array (the right hand side of the assignment statement) with the MATLAB cell concatenation ({ }) operator. For example, the following MATLAB syntax creates a 2-by-2 cell array by assignment: D(2,2) = { 'jones' }.

With content addressing, you use the braces ({ }) operator on the left hand side of the assignment statement to indicate that you want to affect the value contained in the cell. On the right hand side of the assignment statement, you do not need to specify braces. For example, the following MATLAB syntax creates a 2-by-2 cell array by assignment: D{2,2} = ''jones'.

You can use either indexing method interchangeably: the result is the same. For more information about using indexing to access elements in a cell array, see Chapter 4.

Using Cell Indexing to Create a Cell Array.   

The MATLAB C++ Math Library uses the cellhcat() routine to emulate the cell array concatenation ({ }) operator in cell indexing statements.

For example, the following code fragment creates a 2-by-2 cell array by assigning a value to element at row 2, column 2. This example is the same as the MATLAB syntax D(2,2) = { 'jones' }. Note that you must declare the cell array before using it in the cell indexing statement.

mwArray D;

D(2,2) = cellhcat("jones");

cout << D << endl;

This produces the following output:

   []       []
   []  'jones'

Using Content Indexing to Create a Cell Array.   

The MATLAB C++ Math Library uses the mwArray::cell() member function to emulate the use of the braces operator in content indexing statements.

The following code fragment illustrates how to use content indexing to create a cell array by assignment. Note that you must declare the array before using it in the content indexing statement. This example is the same as the MATLAB syntax Z{2,2} = 'jones'.

mwArray Z;

Z.cell(2,2) = "jones";

cout << Z << endl;

This produces the following output:

   []       []
   []  'jones'

Note    Do not confuse the mwArray::cell() member function with the cell() library routine. The cell() library routine creates arrays of empty cells.

Cell Arrays

Displaying the Contents of a Cell Array