Main Content

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, Z is a fixed-size array.

function Z = myfcn()
Z = zeros(1,4);
end

The size of the first dimension is 1 and the size of the second dimension is 4.

If the code generator cannot determine the size of a dimension or the code generator determines that the size changes, then the dimension is 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.

For a MATLAB Function block, you cannot use dynamic memory allocation for parameters. Parameters must be fixed-size.

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 in a MATLAB Function Block.

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, for MATLAB Function blocks, support for variable-size arrays is enabled. To disable this support:

  1. In the MATLAB Function Block Editor, select Edit Data.

  2. Clear the Support variable-size arrays check box.

Variable-Size Arrays in a MATLAB Function 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 MATLAB Function Report.

This image shows a code generation report with several kinds of sizes for the second dimension of three arrays. The second dimension of y is fixed-size, n is fixed-size, and x is unbounded and variable-size.

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 your code specifies that an array is variable-size, but the code generator determined that it does not change size.

This image shows a code generation report with several kinds of sizes for the second dimension of three arrays. y is fixed-size, n is fixed-size, and Z is variable-size but did not change size during execution.

Related Topics