coder.varsize

Package: coder

Declare variable-size data

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' must be a quoted string that represents a variable or structure field. 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-sized 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-sized 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 may add the declaration before the first assignment to each 'varn'.

coder.varsize cannot be applied to global variables.

coder.varsize is not supported for MATLAB® class properties.

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

expand all

Develop a simple stack that varies in size up to 32 elements as you push and pop data at run time.

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 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.

Declare a variable-size structure field.

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.

More About

expand 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 can reduce speed of generated code. To avoid this, use the syntax coder.varsize('var1', 'var2', ..., ubound) to specify an upper bound for the array size (if you know it in advance).

See Also

| | |

Was this topic helpful?