Specify Cell Array Inputs at the Command Line - MATLAB & Simulink (original) (raw)

To specify cell array inputs at the command line, use the same methods that you use for other types of inputs. You can:

Provide an example cell array input to the -args option of the codegen command.
Provide a coder.CellType object to the -args option of the codegen command. To create a coder.CellType object, use coder.typeof.
Use coder.Constant to specify a constant cell array input.

For code generation, cell arrays are classified as homogeneous or heterogeneous. See Code Generation for Cell Arrays. When you provide an example cell array to codegen or coder.typeof, the function determines whether the cell array type is homogeneous or heterogeneous. If the cell array elements have the same class and size, coder.typeof returns a homogeneous cell array type. If the elements have different classes, coder.typeof returns a heterogeneous cell array type. For some cell arrays, the classification as homogeneous or heterogeneous is ambiguous. For example, the type for {1 [2 3]} can be a 1x2 heterogeneous type. The first element is double and the second element is 1x2 double. The type can also be a 1x3 homogeneous type in which the elements have class double and size 1x:2. For these ambiguous cases, coder.typeof uses heuristics to classify the type as homogeneous or heterogeneous. If you want a different classification, use the coder.CellType makeHomogeneous or makeHeterogeneous methods. The makeHomogeneous method makes a homogeneous copy of a type. The makeHeterogeneous method makes a heterogeneous copy of a type.

The makeHomogeneous and makeHeterogeneous methods permanently assign the classification as homogeneous and heterogeneous, respectively. You cannot later use one of these methods to create a copy that has a different classification.

If you have a test file, you can use coder.getArgTypes to determine input types. In the output cell array of types, for cell array inputs, coder.getArgTypes returns a coder.CellType object. If you want a different classification (homogeneous or heterogeneous), use the makeHomogeneous or makeHeterogeneous methods.

Specify Cell Array Inputs by Example

To specify a cell array input by example, provide an example cell array in the -args option of the codegen command.

For example:

To specify a 1x3 cell array whose elements have class double:
codegen myfunction -args {{1 2 3}} -report
The input argument is a 1x3 homogeneous cell array whose elements are 1x1 double.
To specify a 1x2 cell array whose first element has class char and whose second element has class double:
codegen myfunction -args {{'a', 1}} -report
The input argument is a 1x2 heterogeneous cell array whose first element is 1x1 char and whose second element is 1x1 double.

Specify the Type of the Cell Array Input

To specify the type of a cell array input, use coder.typeof to create a coder.CellType object. Pass the coder.CellType object to the -args option of the codegen command.

For example:

To specify a 1x3 cell array whose elements have class double:
t = coder.typeof({1 2 3});
codegen myfunction -args {t} -report
The input argument is a 1x3 homogeneous cell array whose elements are 1x1 double.
To specify a 1x2 cell array whose first element has class char and whose second element has class double:
t = coder.typeof({'a', 1});
codegen myfunction -args {t}
The input argument is a 1x2 heterogeneous cell array whose first element is a 1x1 char and whose second element is a 1x1 double.

You can also use the advanced function coder.newtype to create a coder.CellType object.

Make a Homogeneous Copy of a Type

If coder.typeof returns a heterogeneous cell array type, but you want a homogeneous type, use the makeHomogeneous method to make a homogeneous copy of the type.

The following code creates a heterogeneous type.

t = coder.typeof({1 [2 3]})

t =

coder.CellType 1x2 heterogeneous cell f0: 1x1 double f1: 1x2 double

To make a homogeneous copy of the type, use:

t =

coder.CellType 1×2 locked homogeneous cell base: 1×:2 double

Alternatively, use this notation:

t = makeHomogeneous(coder.typeof({1 [2 3]}))

t =

coder.CellType 1×2 locked homogeneous cell base: 1×:2 double

The classification as homogeneous is locked (permanent). You cannot later use the makeHeterogeneous method to make a heterogeneous copy of the type.

If the elements of a type have different classes, such as char and double, you cannot use makeHomogeneous to make a homogeneous copy of the type.

If you use coder.cstructname to specify a name for the structure type that represents a type in the generated code, you cannot create a homogeneous copy of the type.

Make a Heterogeneous Copy of a Type

If coder.typeof returns a homogeneous cell array type, but you want a heterogeneous type, use the makeHeterogeneous method to make a heterogeneous copy of the type.

The following code creates a homogeneous type.

t = coder.typeof({1 2 3})

t =

coder.CellType 1x3 homogeneous cell base: 1x1 double

To make the type heterogeneous, use:

t =

coder.CellType 1×3 locked heterogeneous cell f1: 1×1 double f2: 1×1 double f3: 1×1 double

Alternatively, use this notation:

t = makeHeterogeneous(coder.typeof({1 2 3}))

t =

coder.CellType 1×3 locked heterogeneous cell f1: 1×1 double f2: 1×1 double f3: 1×1 double

The classification as heterogeneous is locked (permanent). You cannot later use the makeHomogeneous method to make a homogeneous copy of the type.

If a type is variable size, you cannot use makeHeterogeneous to make a heterogeneous copy of it.

Specify Variable-Size Cell Array Inputs

You can specify variable-size cell array inputs in the following ways:

In the coder.typeof call.
For example, to specify a variable-size cell array whose first dimension is fixed and whose second dimension has an upper bound of 5:
t = coder.typeof({1}, [1 5], [0 1])
t =
coder.CellType
1x:5 homogeneous cell
base: 1x1 double

For elements with the same classes, but different sizes, you can the use coder.typeof size and variable dimensions arguments to create a variable-size homogeneous cell array type. For example, the following code does not use the size and variable dimensions arguments. This code creates a type for a heterogeneous cell array.
t = coder.typeof({1 [2 3]})
t =
coder.CellType
1x2 heterogeneous cell
f0: 1x1 double
f1: 1x2 double
The following code, that uses the size and dimensions arguments, creates a type for a variable-size homogeneous type cell array:
t = coder.typeof({1 [2 3]}, [1 5], [0 1])
t =
coder.CellType
1×:5 locked homogeneous cell
base: 1×:2 double

Use coder.resize.
For example, to specify a variable-size cell array whose first dimension is fixed and whose second dimension has an upper bound of 5:
t = coder.typeof({1});
t = coder.resize(t, [1 5], [0,1])
t =
coder.CellType
1x5 homogeneous cell
base: 1x1 double

You cannot use coder.resize with a heterogeneous cell array type.

Specify Type Name for Heterogeneous Cell Array Inputs

A heterogeneous cell array is represented in the generated code as a structure. To specify the name of the structure type in the generated code, usecoder.cstructname.

For example, to specify the name myname for the cell array type in the generated code:

t = coder.typeof({'a', 1}) t = coder.cstructname(t, 'myname')

t =

coder.CellType 1×2 locked heterogeneous cell myname f1: 1×1 char f2: 1×1 double

If you use coder.cstructname with a homogeneous cell array type,coder.cstructname returns a heterogeneous copy of the type. However, it is a best practice to use the makeHeterogeneous method of the coder.CellType object to make a heterogeneous copy of a homogeneous cell array type. Then, you can use coder.cstructname with the heterogeneous copy of the type.

Specify Constant Cell Array Inputs

To specify that a cell array input is constant, use the coder.Constant function with the -args option of the codegen command. For example:

codegen myfunction -args {coder.Constant({'red',1,'green',2,'blue',3})} -report

The input is a 1x6 heterogeneous cell array. The sizes and classes of the elements are:

1x3 char
1x1 double
1x5 char
1x1 double
1x4 char
1x1 double