coder.varsize - Package: coder

Declare variable-size data

Syntax

coder.varsize('var₁', 'var₂', ...) coder.varsize('var₁', 'var₂', ..., ubound) coder.varsize('var₁', 'var₂', ..., ubound, dims) coder.varsize('var₁', 'var₂', ..., [], dims)

Description

coder.varsize('var₁', 'var₂', ...) declares one or more variables as variable-size data, allowing subsequent assignments to extend their size. Each 'var_n' must be a quoted string that represents a variable or structure field. If the structure field is a structure array, use colon (:) as the index expression, indicating that all elements of the array are variable sized. For example, the expression coder.varsize('data(:).A') declares that the field A inside each element of data is variable sized.

coder.varsize('var₁', 'var₂', ..., 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 'var_n'. If you specify more than one 'var_n', each variable must have the same number of dimensions.

coder.varsize('var₁', 'var₂', ..., 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 'var_n'.

coder.varsize('var₁', 'var₂', ..., [], 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 'var_n' in generated code.

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

You must add the coder.varsize declaration before each 'var_n' is used (read). You may add the declaration before the first assignment to each 'var_n'.

coder.varsize cannot be applied to global variables.

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

This function is for code generation. It has no effect in MATLAB code.

Examples

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. Write subfunction stack to execute the push and pop commands.

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

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 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-sized the field values inside each element of the matrix data.

Generate a MEX function for struct_example:
```
codegen 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.