Main Content

coder.varsize

Declare variable-size data

collapse all in page

Syntax

coder.varsize(varName1,...,varNameN)
coder.varsize(varName1,...,varNameN,ubounds)
coder.varsize(varName1,...,varNameN,ubounds,dims)

Description

example

coder.varsize(varName1,...,varNameN) declares that the variables named varName1,...,varNameN have a variable size. The declaration instructs the code generator to allow the variables to change size during execution of the generated code. With this syntax, you do not specify the upper bounds of the dimensions of the variables or which dimensions can change size. The code generator computes the upper bounds. All dimensions, except singleton dimensions, are allowed to change size.

Use coder.varsize according to these restrictions and guidelines:

  • Use coder.varsize inside a MATLAB® function intended for code generation.

  • The coder.varsize declaration must precede the first use of a variable. For example:

    ...
x = 1;
coder.varsize('x');
disp(size(x));
...

  • Use coder.varsize to declare that an output argument has a variable size or to address size mismatch errors. Otherwise, to define variable-size data, use the methods described in Define Variable-Size Data for Code Generation.

Note

For MATLAB Function blocks, to declare variable-size output variables, use the Symbols pane and Property Inspector. See Declare Variable-Size MATLAB Function Block Variables (Simulink). If you provide upper bounds in a coder.varsize declaration, the upper bounds must match the upper bounds in the Property Inspector.

For more restrictions and guidelines, see Limitations and Tips.

example

coder.varsize(varName1,...,varNameN,ubounds) also specifies an upper bound for each dimension of the variables. All variables must have the same number of dimensions. All dimensions, except singleton dimensions, are allowed to change size.

example

coder.varsize(varName1,...,varNameN,ubounds,dims) also specifies an upper bound for each dimension of the variables and whether each dimension has a fixed size or a variable size. If a dimension has a fixed size, then the corresponding ubound element specifies the fixed size of the dimension. All variables have the same fixed-size dimensions and the same variable-size dimensions.

The code generator uses a colon prefix to denote a variable-size dimension. For example, if the size of an array A is denoted as 3x:5x:Inf, then:

  • The first dimension has a fixed size 3

  • The second dimension is variable-size with an upper bound 5

  • The third dimension is variable-size and unbounded

Examples

collapse all

After a variable is used (read), changing the size of the variable can cause a size mismatch error. Use coder.varsize to specify that the size of the variable can change.

Code generation for the following function produces a size mismatch error because x = 1:10 changes the size of the second dimension of x after the line y = size(x) that uses x.

function [x,y] = usevarsize(n)
%#codegen
x = 1;
y = size(x);
if n > 10
    x = 1:10;
end

To declare that x can change size, use coder.varsize. 

function [x,y] = usevarsize(n)
%#codegen
x = 1;
coder.varsize('x');
y = size(x);
if n > 10
    x = 1:10;
end

If you remove the line y = size(x), you no longer need the coder.varsize declaration because x is not used before its size changes.

Specify that A is a row vector of size 1x:20. This denotes that the second dimension of A has a variable size with an upper bound of 20.

function fcn()
...
coder.varsize('A',[1 20]);
...
end

When you do not provide dims, all dimensions, except singleton dimensions, have a variable size.

Specify that A is an array with size 3x:20. This denotes that the first dimension has a fixed size of three and whose second dimension has a variable size with an upper bound of 20.

function fcn()
...
coder.varsize('A',[3 20], [0 1] );
...
end

In this function, the statement coder.varsize('data.values') declares that the field values inside each element of data has a variable size.

function y = varsize_field()
%#codegen

d = struct('values', zeros(1,0), 'color', 0);
data = repmat(d, [3 3]);
coder.varsize('data.values');

for i = 1:numel(data)
    data(i).color = rand-0.5;
    data(i).values = 1:i;
end

y = 0;
for i = 1:numel(data)
    if data(i).color > 0
        y = y + sum(data(i).values);
    end
end

Specify that cell array C has a fixed-size first dimension and variable-size second dimension with an upper bound of three. The coder.varsize declaration must precede the first use of C.

...
C = {1 [1 2]};
coder.varsize('C', [1 3], [0 1]);
y = C{1};
...
end

Without the coder.varsize declaration, C is a heterogeneous cell array whose elements have the same class and different sizes. With the coder.varsize declaration, C is a homogeneous cell array whose elements have the same class and maximum size.

  • The cell array C is of size 1x:3. The colon denotes that the second dimension of C is variable-size with an upper bound of 3.

  • Each element of C is a 1x:2 array.

Specify that the elements of cell array C are 1x:5 vectors. This denotes that the elements each have a fixed-size first dimension and variable-size second dimension with an upper bound of 5.

...
C = {1 2 3};
coder.varsize('C{:}', [1 5], [0 1]);
C = {1, 1:5, 2:3};
...

You can also specify a specific element of a cell array to be variable-size. For example, in a 1-by-3 cell array x, declare the first element x{1} to be a 1x:10 row vector.

...
x = {1,2,3};
coder.varsize('x{1}', [1 10]);
...

Input Arguments

collapse all

Names of variables to declare as having a variable size, specified as one or more character vectors or string scalars.

Example: coder.varsize('x','y')

Upper bounds for array dimensions, specified as a vector of integer constants.

When you do not specify ubounds, the code generator computes the upper bound for each variable. If the ubounds element corresponds to a fixed-size dimension, the value is the fixed size of the dimension.

Example: coder.varsize('x','y',[1 2])

Indication of whether each dimension has a fixed size or a variable size, specified as a logical vector. Dimensions that correspond to 0 or false in dims have a fixed size. Dimensions that correspond to 1 or true have a variable size.

When you do not specify dims, the dimensions have a variable size, except for the singleton dimensions.

Example: coder.varsize('x','y',[1 2], [0 1])

Limitations

  • The coder.varsize declaration instructs the code generator to allow the size of a variable to change. It does not change the size of the variable. Consider this code:

    ...
x = 7;
coder.varsize('x', [1,5]);
disp(size(x));
...

    After the coder.varsize declaration, x is still a 1-by-1 array. You cannot assign a value to an element beyond the current size of x. For example, this code produces a run-time error because the index 3 exceeds the dimensions of x.

    ...
x = 7;
coder.varsize('x', [1,5]);
x(3) = 1;
...

  • coder.varsize is not supported for a function input argument. Instead:

    • If the function is an entry-point function, specify that an input argument has a variable size by using coder.typeof at the command line. Alternatively, specify that an entry-point function input argument has a variable size by using the Define Input Types step of the app.

    • If the function is not an entry-point function, use coder.varsize in the calling function with the variable that is the input to the called function.

  • For sparse matrices, coder.varsize drops upper bounds for variable-size dimensions.

  • Limitations for using coder.varsize with cell arrays:

    • A cell array can have a variable size only if it is homogeneous. When you use coder.varsize with a heterogeneous cell array, the code generator tries to make the cell array homogeneous. The code generator tries to find a class and maximum size that apply to all elements of the cell array. For example, consider the cell array c = {1, [2 3]}. Both elements can be represented by a double type whose first dimension has a fixed size of 1 and whose second dimension has a variable size with an upper bound of 2. If the code generator cannot find a common class and a maximum size, code generation fails. For example, consider the cell array c = {'a',[2 3]}. The code generator cannot find a class that can represent both elements because the first element is char and the second element is double.

    • If you use the cell function to define a fixed-size cell array, you cannot use coder.varsize to specify that the cell array has a variable size. For example, this code causes a code generation error because x = cell(1,3) makes x a fixed-size,1-by-3 cell array.

      ...
x = cell(1,3);           
coder.varsize('x',[1 5])
...

      You can use coder.varsize with a cell array that you define by using curly braces. For example: 

      ...
x = {1 2 3}; 
coder.varsize('x',[1 5])
...

    • To create a variable-size cell array by using the cell function, use this code pattern:

      function mycell(n)
%#codegen
x = cell(1,n);   
for i = 1:n
    x{i} = i;
end
end

      See Assign Values to All Cell Array Elements.

      To specify upper bounds for the cell array, use coder.varsize.

      function mycell(n)
%#codegen
x = cell(1,n);   
for i = 1:n
    x{i} = i;
coder.varsize('x',[1,20]);
end
end

  • coder.varsize is not supported for:

    • Global variables

    • MATLAB classes or class properties

    • String scalars

More About

collapse all

Singleton Dimension

Dimension for which size(A,dim) = 1.

Tips

  • In a code generation report or a MATLAB Function report, a colon (:) indicates that a dimension has a variable size. For example, a size of 1x:2 indicates that the first dimension has a fixed size of one and the second dimension has a variable size with an upper bound of two.

  • If you use coder.varsize to specify that the upper bound of a dimension is 1, by default, the dimension has a fixed size of 1. To specify that the dimension can be 0 (empty array) or 1, set the corresponding element of the dims argument to true. For example, this code specifies that the first dimension of x has a fixed size of 1 and the other dimensions have a variable size of 5.

    coder.varsize('x',[1,5,5])

    In contrast, this code specifies that the first dimension of x has an upper bound of 1 and has a variable size (can be 0 or 1).

    coder.varsize('x',[1,5,5],[1,1,1])

  • If you use input variables or the result of a computation using input variables to specify the size of an array, it is declared as variable-size in the generated code. Do not re-use coder.varsize on the array, unless you also want to specify an upper bound for its size.

  • If you do not specify upper bounds with a coder.varsize declaration and the code generator is unable to determine the upper bounds, the generated code uses dynamic memory allocation. Dynamic memory allocation can reduce the speed of generated code. To avoid dynamic memory allocation, specify the upper bounds by providing the ubounds argument.

Version History

Introduced in R2011a

See Also

Topics