Embedded MATLAB™

Specifying Variable Numbers of Arguments in Embedded MATLAB Functions

Using varargin and varargout to Specify Variable Length Argument Lists

You can use varargin and varargout for passing and returning variable numbers of parameters to Embedded MATLAB functions called from a top-level function.

Common applications of varargin and varargout in Embedded MATLAB functions include:

• Using for-loops to apply operations to a variable number of arguments

• Implementing wrapper functions that accept any number of inputs and pass them to another function

• Passing variable numbers of property/value pairs as arguments to a function

The Embedded MATLAB subset relies on loop unrolling to produce simple and efficient code for varargin and varargout. This technique permits most common uses of varargin and varargout, but not all (see Rules for Using Variable Length Argument Lists in Embedded MATLAB Functions). This following sections explain how to code effectively using these constructs.

For more information about using varargin and varargout in MATLAB functions, see Passing Variable Numbers of Arguments in the MATLAB Programming Fundamentals documentation.

Back to Top

Supported Index Expressions

In MATLAB, varargin and varargout are cell arrays. The Embedded MATLAB subset does not support cell arrays in general, but does allow you to use the most common syntax — curly braces {} — for indexing into varargin and varargout arrays, as in this example:

%#eml
function [x,y,z] = fcn(a,b,c)
[x,y,z] = subfcn(a,b,c);

function varargout = subfcn(varargin)
for i = 1:length(varargin)
   varargout{i} = varargin{i};
end

You can use the following index expressions. The exp arguments must be constant expressions or depend on a loop index variable.

Note   The use of () is not supported for indexing into varargin and varargout arrays.

Back to Top

Using varargin and varargout in for-Loops

You can use varargin and varargout in for-loops to apply operations to a variable number of arguments. To index into varargin and varargout arrays, Embedded MATLAB functions must be able to compute the value of the loop index variable at compile time. Therefore, Embedded MATLAB functions attempt to automatically unroll these for-loops. Unrolling eliminates the loop logic by creating a separate copy of the loop body in the generated code for each iteration. Within each iteration, the loop index variable becomes a constant. For example, the following function automatically unrolls its for-loop in the generated code:

%#eml
function [cmlen,cmwth,cmhgt] = conv_2_metric(inlen,inwth,inhgt)

[cmlen,cmwth,cmhgt] = inch_2_cm(inlen,inwth,inhgt);

function varargout = inch_2_cm(varargin)
for i = 1:length(varargin)
   varargout{i} = varargin{i} * 2.54;
end

When to Force Loop Unrolling

To automatically unroll for-loops containing varargin and varargout expressions, Embedded MATLAB functions must be able to determine the relationship between the loop index expression and the index variable at compile time.

In the following example, the function fcn cannot detect a logical relationship between the index expression j and the index variable i:

%#eml
function [x,y,z] = fcn(a,b,c)

[x,y,z] = subfcn(a,b,c);

function varargout = subfcn(varargin)
j = 0;
for i = 1:length(varargin)
    j = j+1;
    varargout{j} = varargin{j};
end

As a result, the function does not unroll the loop and generates a compilation error:

Non-constant expression or empty matrix. 
This expression must be constant because 
its value determines the size or class of some expression.

To correct the problem, you can force loop unrolling by wrapping the loop header in the function eml.unroll, as follows:

%#eml
function [x,y,z] = fcn(a,b,c)
  [x,y,z] = subfcn(a,b,c);
 
function varargout = subfcn(varargin)
  j = 0;
  for i = eml.unroll(1:length(varargin))
      j = j + 1;
      varargout{j} = varargin{j};
  end;

Example: Using Variable Numbers of Arguments in a for-Loop

The following example multiplies a variable number of input dimensions in inches by 2.54 to convert them to centimeters:

%#eml
function [cmlen,cmwth,cmhgt] = conv_2_metric(inlen,inwth,inhgt)

[cmlen,cmwth,cmhgt] = inch_2_cm(inlen,inwth,inhgt);

function varargout = inch_2_cm(varargin)
for i = 1:length(varargin)
   varargout{i} = varargin{i} * 2.54;
end

Key Points About the Example.  

• varargin and varargout appear in the subfunction inch_2_cm, not in the top-level function conv_2_metric.

• The index into varargin and varargout is a for-loop variable

For more information, see Rules for Using Variable Length Argument Lists in Embedded MATLAB Functions.

Back to Top

Implementing Wrapper Functions with varargin and varargout

You can use varargin and varargout to write wrapper functions that accept any number of inputs and pass them directly to another function.

Example: Passing Variable Numbers of Arguments from One Function to Another

The following example passes a variable number of inputs to different optimization functions, based on a specified input method:

%#eml
function answer = fcn(method,a,b,c)
answer = optimize(method,a,b,c);

function answer = optimize(method,varargin)
  if strcmp(method,'simple')
    answer = simple_optimization(varargin{:});
  else
    answer = complex_optimization(varargin{:});
  end
...

Key Points About the Example.  

• You can use {:} to read all elements of varargin and pass them to another function.

• You can mix variable and fixed numbers of arguments in Embedded MATLAB functions.

For more information, see Rules for Using Variable Length Argument Lists in Embedded MATLAB Functions.

Back to Top

Passing Property/Value Pairs with varargin

You can use varargin to pass property/value pairs in Embedded MATLAB functions. However, you must take precautions to avoid type mismatch errors when evaluating varargin array elements in a for-loop:

For example, in the following function test1, the sizes of the property strings and numeric values are not the same in each pair:

%#eml
function test1
    v = create_value('size', 18, 'rgb', [240 9 44]);
end
 
function v = create_value(varargin) 
    v = new_value();
    for i = 1 : 2 : length(varargin)
        name = varargin{i};
        value = varargin{i+1};
        switch name
            case 'size'
                v = set_size(v, value);
            case 'rgb'
                v = set_color(v, value);
            otherwise
        end
    end
end
...

The Embedded MATLAB subset defines the size, type, and complexity of a local variable based on its first assignment. In this example, the first assignments occur in the first iteration of the for-loop:

• Defines local variable name with size equal to 4

• Defines local variable value with a size of scalar

However, in the second iteration, the size of the property string changes to 3 and the size of the numeric value changes to a vector, resulting in a type mismatch error. To avoid such errors, reference varargin array values directly, not through local variables, as highlighted in this code:

%#eml
function test1
    v = create_value('size', 18, 'rgb', [240 9 44]);
end
 
function v = create_value(varargin) 
    v = new_value();
    for i = 1 : 2 : length(varargin)
            switch varargin{i}
            case 'size'
                v = set_size(v, varargin{i+1});
            case 'rgb'
                v = set_color(v, varargin{i+1});
            otherwise
        end
    end
end
...

Back to Top

Rules for Using Variable Length Argument Lists in Embedded MATLAB Functions

The Embedded MATLAB subset supports variable numbers of arguments with the following limitations:

 Do not use varargin or varargout in top-level functions

%#eml
function varargout = inch_2_cm(varargin)
for i = 1:length(varargin)
   varargout{i} = varargin{i} * 2.54;
end

%#eml
function [cmL, cmW, cmH] = conv_2_metric(inL, inW, inH)
[cmL, cmW, cmH] = inch_2_cm(inL, inW, inH);

function varargout = inch_2_cm(varargin)
for i = 1:length(varargin)
   varargout{i} = varargin{i} * 2.54;
end

 Use curly braces {} to index into the argument list

 Ensure that Embedded MATLAB functions can compute indices at compile time

 Do not write to varargin

Back to Top

Working with Function Handles

Using M-Lint with Embedded MATLAB Code