coder.varsize

Package: coder

Declare variable-size array

collapse all in page

Syntax

coder.varsize('var1', 'var2', ...)
coder.varsize('var1', 'var2', ..., ubound)
coder.varsize('var1', 'var2', ..., ubound, dims)
coder.varsize('var1', 'var2', ..., [], dims)

Description

coder.varsize('var1', 'var2', ...) declares one or more variables as variable-size data, allowing subsequent assignments to extend their size. Each 'varn' is the name of a variable or structure field enclosed in quotes. If the structure field belongs to an array of structures, use colon (:) as the index expression to make the field variable-size for all elements of the array. For example, the expression coder.varsize('data(:).A') declares that the field A inside each element of data is variable sized.

coder.varsize('var1', 'var2', ..., ubound) declares one or more variables as variable-size data with an explicit upper bound specified in ubound. The argument ubound must be a constant, integer-valued vector of upper bound sizes for every dimension of each 'varn'. If you specify more than one 'varn', each variable must have the same number of dimensions.

coder.varsize('var1', 'var2', ..., ubound, dims) declares one or more variables as variable size with an explicit upper bound and a mix of fixed and varying dimensions specified in dims. The argument dims is a logical vector, or double vector containing only zeros and ones. Dimensions that correspond to zeros or false in dims have fixed size; dimensions that correspond to ones or true vary in size. If you specify more than one variable, each fixed dimension must have the same value across all 'varn'.

coder.varsize('var1', 'var2', ..., [], dims) declares one or more variables as variable size with a mix of fixed and varying dimensions. The empty vector [] means that you do not specify an explicit upper bound.

When you do not specify ubound, the upper bound is computed for each 'varn' in generated code.

When you do not specify dims, dimensions are assumed to be variable except the singleton ones. A singleton dimension is a dimension for which size(A,dim) = 1.

You must add the coder.varsize declaration before each 'varn' is used (read). You can add the declaration before the first assignment to each 'varn'. However, for a cell array element, the coder.varsize declaration must follow the first assignment to the element. For example:

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

You cannot use coder.varsize outside the MATLAB® code intended for code generation. For example, the following code does not declare the variable, var, as variable-size data:

coder.varsize('var',10);
codegen -config:lib MyFile -args var

Instead, include the coder.varsize statement inside MyFile to declare var as variable-size data. Alternatively, you can use coder.typeof to declare var as variable-size outside MyFile. It can then be passed to MyFile during code generation using the -args option. For more information, see coder.typeof.

Examples

collapse all

Write primary function test_stack to issue commands for pushing data on and popping data from a stack. 

function test_stack %#codegen
    % The directive %#codegen indicates that the function
    % is intended for code generation
    stack('init', 32);
    for i = 1 : 20
        stack('push', i);
    end
    for i = 1 : 10
        value = stack('pop');
        % Display popped value
        value
    end
end

Write local function stack to execute the push and pop commands.

function y = stack(command, varargin)
    persistent data;
    if isempty(data)
        data = ones(1,0);
    end
    y = 0;
    switch (command)
    case {'init'}
        coder.varsize('data', [1, varargin{1}], [0 1]);
        data = ones(1,0);
    case {'pop'}
        y = data(1);
        data = data(2:size(data, 2));
    case {'push'}
        data = [varargin{1}, data];
    otherwise
        assert(false, ['Wrong command: ', command]);
    end
end

The variable data is the stack. The statement coder.varsize('data', [1, varargin{1}], [0 1]) declares that:

  • data is a row vector

  • Its first dimension has a fixed size

  • Its second dimension can grow to an upper bound of 32

Generate a MEX function for test_stack:

codegen -config:mex test_stack

codegen generates a MEX function in the current folder.

Run test_stack_mex to get these results:

value =
    20

value =
    19

value =
    18

value =
    17

value =
    16

value =
    15

value =
    14

value =
    13

value =
    12

value =
    11

At run time, the number of items in the stack grows from zero to 20, and then shrinks to 10.

Write a function struct_example that declares an array data, where each element is a structure that contains a variable-size field:

function y=struct_example() %#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

The statement coder.varsize('data(:).values') marks as variable-size the field values inside each element of the matrix data.

Generate a MEX function for struct_example:

codegen -config:mex struct_example

Run struct_example.

Each time you run struct_example you get a different answer because the function loads the array with random numbers.

Write the function make_varsz_cell that defines a local cell array variable c whose elements have the same class, but different sizes. Use coder.varsize to indicate that c has variable-size.

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

Generate a C static library.

codegen -config:lib make_varsz_cell -report

In the report, view the MATLAB variables.

c is a 1x:3 homogeneous cell array whose elements are 1x:2 double.

Write the function mycell that defines a local cell array variable c. Use coder.varsize to make the elements of c variable-size.

function y =  mycell()
c = {1 2 3};
coder.varsize('c{:}', [1 5], [0 1]);
y = c;
end

Generate a C static library.

codegen -config:lib mycell -report

In the report, view the MATLAB variables.

The elements of c are 1-by-:5 arrays of doubles.

Limitations

  • If you use the cell function to create a cell array, you cannot use coder.varsize with that cell array.

  • If you use coder.varsize with a cell array element, the coder.varsize declaration must follow the first assignment to the element. For example:

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

  • You cannot use coder.varsize with a cell array input that is heterogeneous.

  • You cannot use coder.varsize with global variables.

  • You cannot use coder.varsize with MATLAB class properties.

More About

collapse all

Tips

  • If you use input variables (or 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 use coder.varsize on the array again, unless you also want to specify an upper bound for its size.

  • Using coder.varsize on an array without explicit upper bounds causes dynamic memory allocation of the array. This dynamic memory allocation can reduce the speed of generated code. To avoid dynamic memory allocation, use the syntax coder.varsize('var1', 'var2', ..., ubound) to specify an upper bound for the array size (if you know it in advance).

  • A cell array can be variable size only if it is homogeneous. When you use coder.varsize with a cell array, the code generator tries to make the cell array homogeneous. It tries to find a class and size that apply to all elements of the cell array. For example, if the first element is double and the second element is 1x2 double, all elements can be represented as 1x:2 double. If the code generator cannot find a common class and size, code generation fails. For example, suppose that the first element of a cell array is char and the second element is double. The code generator cannot find a class that can represent both elements.

See Also

| |

Introduced in R2011a

Was this topic helpful?
MATLAB Coder Documentation
Other Documentation
Support