Code Generation for Variable-Size Arrays

For code generation, an array dimension is fixed-size or variable-size. If the code generator can determine the size of the dimension and that the size of the dimension does not change, then the dimension is fixed-size. When all dimensions of an array are fixed-size, the array is a fixed-size array. In the following example, X is a fixed-size scalar (1x1), Y is a fixed-size row vector (1x4), and Z is a fixed-size matrix (3x3).

function myfcn()
X = 0;
Y = zeros(1,4);
Z = ones(3,3);
end

If the code generator cannot determine the size of a dimension or if the code generator determines that the size of the dimension changes, then it defines the dimension as variable-size. When at least one of its dimensions is variable-size, an array is a variable-size array.

A variable-size dimension is either bounded or unbounded. A bounded dimension has a fixed upper size. An unbounded dimension does not have a fixed upper size.

In the following example, the second dimension of Z is bounded, variable-size. It has an upper bound of 16.

function s = myfcn(n)
if (n > 0)
    Z = zeros(1,4);
else
    Z = zeros(1,16);
end
s = length(Z);

In the following example, if the value of n is unknown at compile time, then the second dimension of Z is unbounded.

function s = myfcn(n)
Z = rand(1,n);
s = sum(Z);
end

You can define variable-size arrays by:

• Using constructors, such as zeros, with a nonconstant dimension

• Assigning multiple, constant sizes to the same variable before using it

• Declaring all instances of a variable to be variable-size by using coder.varsize

For more information, see Define Variable-Size Data for Code Generation.

You can control whether variable-size arrays are allowed for code generation. See Enabling and Disabling Support for Variable-Size Arrays.

Memory Allocation for Variable-Size Arrays

For fixed-size arrays and variable-size arrays whose size is less than a threshold, the code generator allocates memory statically on the stack. For unbounded, variable-size arrays and variable-size arrays whose size is greater than or equal to a threshold, the code generator allocates memory dynamically on the heap.

You can control whether dynamic memory allocation is allowed or when it is used for code generation. See Control Memory Allocation for Variable-Size Arrays.

The code generator represents dynamically allocated data as a structure type called emxArray. The code generator generates utility functions that create and interact with emxArrays. If you use Embedded Coder^®, you can customize the generated identifiers for the emxArray types and utility functions. See Identifier Format Control (Embedded Coder).

Enabling and Disabling Support for Variable-Size Arrays

By default, support for variable-size arrays is enabled. To modify this support:

• In a code configuration object, set the EnableVariableSizing parameter to true or false.

• In the MATLAB^® Coder™ app, in the Memory settings, select or clear the Enable variable-sizing check box.

Variable-Size Arrays in a Code Generation Report

You can tell whether an array is fixed-size or variable-size by looking at the Size column of the Variables tab in a code generation report.

A colon (:) indicates that a dimension is variable-size. A question mark (?) indicates that the size is unbounded. For example, a size of 1-by-:? indicates that the size of the first dimension is fixed-size 1 and the size of the second dimension is unbounded, variable-size. Italics indicates that the code generator produced a variable-size array, but the size of the array does not change during execution.

Related Topics

• Control Memory Allocation for Variable-Size Arrays
• Specify Upper Bounds for Variable-Size Arrays
• Define Variable-Size Data for Code Generation