varargin - Variable-length input argument list - MATLAB (original) (raw)

Variable-length input argument list

Syntax

Description

varargin is an input variable in a function definition statement that enables the function to accept any number of input arguments. Specify varargin by using lowercase characters. After any explicitly declared inputs, includevarargin as the last input argument.

When the function executes, varargin is a 1-by-N cell array, where N is the number of inputs that the function receives after the explicitly declared inputs. If the function receives no inputs after the explicitly declared inputs, thenvarargin is an empty cell array.

example

Examples

expand all

Define a function in a file named acceptVariableNumInputs.m that accepts a variable number of inputs and displays the values of each input.

type acceptVariableNumInputs

function acceptVariableNumInputs(varargin) disp("Number of input arguments: " + nargin) celldisp(varargin) end

Call the function with several inputs.

acceptVariableNumInputs(ones(3),'some text',pi)

Number of input arguments: 3

varargin{1} =

 1     1     1
 1     1     1
 1     1     1

varargin{2} =

some text

varargin{3} =

3.1416

Define a function in a file named definedAndVariableNumInputs.m that expects two inputs and accepts an additional number of inputs.

type definedAndVariableNumInputs

function definedAndVariableNumInputs(X,Y,varargin) disp("Total number of input arguments: " + nargin)

formatSpec = "Size of varargin cell array: %dx%d";
str = compose(formatSpec,size(varargin));
disp(str)

end

Call the function with several inputs.

definedAndVariableNumInputs(7,pi,rand(4),datetime('now'),'hello')

Total number of input arguments: 5 Size of varargin cell array: 1x3

Call the function with two inputs. varargin is an empty cell array.

definedAndVariableNumInputs(13,42)

Total number of input arguments: 2 Size of varargin cell array: 0x0

Define a function in a file named variableNumInputAndOutput.m that accepts a variable number of inputs and outputs.

type variableNumInputAndOutput

function varargout = variableNumInputAndOutput(varargin) disp(['Number of provided inputs: ' num2str(length(varargin))]) disp(['Number of requested outputs: ' num2str(nargout)])

for k = 1:nargout
    varargout{k} = k;
end

end

Call the function with two inputs and three outputs.

[d,g,p] = variableNumInputAndOutput(6,'Nexus')

Number of provided inputs: 2 Number of requested outputs: 3

Call the function again with no inputs or outputs.

variableNumInputAndOutput

Number of provided inputs: 0 Number of requested outputs: 0

Extended Capabilities

expand all

Usage notes and limitations:

If you use varargin to define an argument to an entry-point (top-level) function, the code generator produces a C/C++ function with a fixed number of input arguments. The number of arguments that you specify when you generate code determines the fixed number of arguments.
You cannot write to varargin. If you want to write to input arguments, first copy the input arguments into a local variable.
The index into varargin must be a compile-time constant.

Usage notes and limitations:

You cannot write to varargin. If you want to write to input arguments, first copy the input arguments into a local variable.
The index into varargin must be a compile-time constant.

Version History

Introduced before R2006a

expand all

You can use the varargin in a MATLAB Function block that has the HDL block property Architecture set toMATLAB Datapath and multi-index input arguments into cell arrays. For example, you can now generate HDL code for this code snippet:

Specifying a variable number of input arguments using varargin shows improved performance. For example, in a file namedtimingTest.m in your current folder, create a function that expects one input and accepts an additional number of inputs.

function timingTest(x,varargin) n = 1e6; tic for i = 1:n y = myFun(x,varargin{:}); end toc end

function y = myFun(x,varargin) if nargin == 1 y = x; elseif nargin == 3 y = x + varargin{1} + varargin{2}; else y = NaN; end end

The amount of improvement depends on whether varargin is empty. The performance improvement is most significant whenvarargin is empty.

Empty varargin — Time this code by runningtimingTest(1). The code is about 22x faster than in the previous release. The approximate execution times are:
R2022b: 0.404 s
R2023a: 0.018 s
Nonempty varargin — Time this code by runningtimingTest(1,2,3). The code is about 2x faster than in the previous release. The approximate execution times are:
R2022b: 1.428 s
R2023a: 0.734 s

The code was timed on a Windows® 10, Intel® Xeon® CPU E5-1650 v4 @ 3.60 GHz test system.

You can generate HDL code for functions in MATLAB Function blocks with HDL block property set to MATLAB Datapath. These functions can use input argumentvarargin. HDL function checkhdl can determine if cell arrays are accessed and initialized correctly usingvarargin.