eml.varsize - Package: eml

Declare variable-size data

Syntax

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

Description

eml.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 eml.varsize('data(:).A') declares that the field A inside each element of data is variable sized.

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

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

eml.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, Embedded MATLAB technology computes the upper bound for each 'var_n'.

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

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

This function has no effect in MATLAB code; it applies to the Embedded MATLAB subset only.

Examples

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

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 %#eml
    % The directive %#eml declares the function
    % to be Embedded MATLAB compliant
    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'}
        eml.varsize('data', [1, varargin{1}], [0 1]);
        data = ones(1,0);
    case {'pop'}
        y = data(1);
        data = data(2:size(data, 2));
    case {'push'}
        % The %#ok comment below indicates that use of
        % variable-size variable is intentional.
        data = [varargin{1}, data]; %#ok<EMGRO>
    otherwise
        assert(false, ['Wrong command: ', command]);
    end
end

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

data i s 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:
```
emlmex test_stack
```
emlmex 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 runtime, 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() %#eml

  d = struct('values', zeros(1,0), 'color', 0);
  data = repmat(d, [3 3]);
  eml.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 eml.varsize('data(:).values') marks as variable-sized the field values inside each element of the matrix data.

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