coder.varsize(varName1,...,varNameN) instructs the code generator to allow the dimensions of variables varName1,...,varNameN to change size at run time. The code generator attempts to determine the upper bound for each dimension of each variable. Dimensions with size 1, also known as singleton dimensions, remain fixed size. To instruct the code generator to allow singleton dimensions to vary in size, you must specify variable-size upper bounds by using the upperBounds and variableSize arguments. For more information about defining variable-size data in MATLAB^® code for code generation, see Define Variable-Size Data for Code Generation.

example

coder.varsize(varName1,...,varNameN,upperBounds) specifies an upper bound for each dimension of the variables varName1,...,varNameN. Singleton dimensions remain fixed size.

example

coder.varsize(varName1,...,varNameN,upperBounds,variableSize) specifies, for each upper bound specified in upperBounds, whether that upper bound is fixed size or variable size. To instruct the code generator to allow a singleton dimension to vary in size, explicitly specify an variable-size upper bound.

example

collapse all

function out = changeSizeAfterUse(n) %#codegen
x = zeros(3,3);
numel(x); % use x by passing it to another function
if n < 10
    x = zeros(4,4); % change size of x depending on run-time input
end
out = x;
end

function out = changeSizeAfterUse(n) %#codegen
x = zeros(3,3);
coder.varsize("x");
numel(x); % use x by passing it to another function
if n < 10
    x = zeros(4,4); % change size of x depending on run-time input
end
out = x;
end

function varSizeUpperBounds() %#codegen
A = 0;
coder.varsize("A",[1 20]);
end

function fcn2() %#codegen
A = [0 0 0];
coder.varsize("A",[1 3 20],[true false true]);
end

function out = varSizeFields(n) %#codegen
s = struct("observations1",zeros(2,2),"observations2",zeros(2,2), ...
    "values",zeros(1,1));
coder.varsize("s.observations1","s.observations2",[2 Inf],[false true]);
coder.varsize("s.values",[1 10]);
if n <= 10
    s.observations1 = [1:n;rand(1,n)];
    s.values = randi(100,1,n);
end
if n > 0
    s.observations2 = [1:15;zeros(1,15)];
end
out = s;
end

function varSizeElement %#codegen
ca1 = {[1 2] [3 4] [5 6]};
ca2 = {[1 2] [3 4] [5 6]};
coder.varsize("ca1{:}",[1 5]);
coder.varsize("ca2{2}",[2 2]);
ca1{1} = 1;
ca1{2} = 1:5;
ca1{3} = 1:3;
ca2{1} = [5 6];
ca2{2} = [1 2;3 4];
ca2{3} = [7 8];
end

function out = boundedVarSize1(n) %#codegen
x = zeros(3,3);
coder.varsize("x",[5 5])
x = zeros(n,n);
out = x;
end

codegen boundedVarSize -args {0} -report

Code generation successful: View report

function out = boundedVarSize2(n) %#codegen
x = zeros(3,3);
coder.varsize("x",[5 5])
if n <= 5
    x = zeros(n,n);
else
    x = zeros(5,5);
end
out = x;
end

collapse all

• Code generation does not support using coder.varsize with global variables, MATLAB classes, and MATLAB class properties.

• Code generation does not support using coder.varsize with strings. See Resolve Error: coder.varsize Not Supported for Strings.

• The coder.varsize directive 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 snippet:

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

  After the coder.varsize directive, 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;
  ...

• You cannot call coder.varsize on function input arguments. 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 MATLAB Coder™ 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 treats variable-size dimensions as unbounded.

• To use coder.varsize with a cell array, the cell array must be homogeneous. See Cell Array Limitations for Code Generation.

• In many cases, the code generator can determine that the size of a variable can change at run time. In such cases, you do not need to use the coder.varsize directive. Use coder.varize only if the code generator produces a size overflow error or if you want to specify upper bounds.

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

• If you do not specify upper bounds in the coder.varsize declaration and the code generator is unable to infer upper bounds, the generated code uses dynamic memory allocation. Dynamic memory allocation can reduce the speed of the generated code. In some cases, you can avoid dynamic memory allocation by specifying upper bounds by using the upperBounds argument.

• If you use coder.varsize to specify that the upper bound of a dimension is 1, the dimension has a fixed size of 1 by default. To specify that the dimension can be 0 or 1, set the corresponding element of the variableSize vector to true. For example, this directive 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 is variable size with an upper bound of 1.

  coder.varsize("x",[1 5 5],[true true true])

• When you use the output of an extrinsic function, the code generator is unable to determine the size of this output at code generation time. Use coder.varsize to instruct the code generator to treat the variable you use to store this output as variable size. See Use Variable-Size Output of Extrinsic Function at Run Time.

• Under certain circumstances, you can force a cell array to be homogeneous by using coder.varsize. See Control Whether a Cell Array Is Variable-Size.