Code Generation for Cell Arrays

When you generate code from MATLAB^® code that contains cell arrays, the code generator classifies the cell arrays as homogeneous or heterogeneous. This classification determines how a cell array is represented in the generated code. It also determines how you can use the cell array in MATLAB code from which you generate code.

When you use cell arrays in MATLAB code that is intended for code generation, you must adhere to certain restrictions. See Cell Array Limitations for Code Generation.

Homogeneous vs. Heterogeneous Cell Arrays

A homogeneous cell array has these characteristics:

• The cell array is represented as an array in the generated code.

• All elements have the same properties. The type associated with the cell array specifies the properties of all elements rather than the properties of individual elements.

• The cell array can be variable-size.

• You can index into the cell array with an index whose value is determined at run time.

A heterogeneous cell array has these characteristics:

• The cell array is represented as a structure in the generated code. Each element is represented as a field of the structure.

• The elements can have different properties. The type associated with the cell array specifies the properties of each element individually.

• The cell array cannot be variable-size.

• You must index into the cell array with a constant index or with for-loops that have constant bounds.

The code generator uses heuristics to determine the classification of a cell array as homogeneous or heterogeneous. It considers the properties (class, size, complexity) of the elements and other factors, such as how you use the cell array in your program. Depending on how you use a cell array, the code generator can classify a cell array as homogeneous in one case and heterogeneous in another case. For example, consider the cell array {1 [2 3]}. The code generator can classify this cell array as a heterogeneous 1-by-2 cell array. The first element is double scalar. The second element is a 1-by-2 array of doubles. However, if you index into this cell array with an index whose value is determined at run time, the code generator classifies it as a homogeneous cell array. The elements are variable-size arrays of doubles with an upper bound of 2.

Controlling Whether a Cell Array Is Homogeneous or Heterogeneous

For cell arrays with certain characteristics, you cannot control the classification as homogeneous or heterogeneous:

• If the elements have different classes, the cell array must be heterogeneous.

• If the cell array is variable-size, it must be homogeneous.

• If you index into the cell array with an index whose value is determined at run time, the cell array must be homogeneous.

For other cell arrays, you can control the classification as homogeneous or heterogeneous.

To control the classification of cell arrays that are entry-point function inputs:

• At the command line, use the coder.CellType methods makeHomogeneous and makeHeterogeneous.

• In the MATLAB Coder™ app, select cell (Homogeneous) or cell (Heterogeneous) from the type menu. See Specify Types of Entry-Point Inputs Using the App.

To control the classification of cell arrays that are not entry-point function inputs:

• If the cell array is fixed-size, you can force an otherwise homogeneous cell array to be heterogeneous by using coder.cstructname. For example:

  function y =  mycell()
  %#codegen
  c = {1 2 3};
  coder.cstructname(c, 'myname');
  y = c;
  end

• If the cell array elements have the same class, you can force a cell array to be homogeneous by using coder.varsize. See Control Whether a Cell Array Is Variable-Size.

Naming the Structure Type That Represents a Heterogeneous Cell Array in the Generated Code

The code generator represents a heterogeneous cell array as a structure in the generated code. You can name the generated structure type. You cannot name the fields of the structure.

If the cell array is an entry-point function input, see Define Cell Array Inputs. If the cell array is not an entry-point function input, use coder.cstructname in the MATLAB function. For example:

function y =  mycell()
%#codegen
c = {1 'a'};
coder.cstructname(c, 'myname');
y = c;
end

Cell Arrays in Reports

To see whether a cell array is homogeneous or heterogeneous, view the variable in the code generation report.

For a homogeneous cell array, the report has one entry that specifies the properties of all elements. The notation {:} indicates that all elements of the cell array have the same properties.

For a heterogeneous cell array, the report has an entry for each element. For example, for a heterogeneous cell array c with two elements, the entry for c{1} shows the properties for the first element. The entry for c{2} shows the properties for the second element.