varargin

Variable-length input argument list

Syntax

varargin

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, include varargin 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, then varargin is an empty cell array.

Examples

Variable Number of Function Inputs

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

 

varargin and Declared Inputs

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

Variable Number of Inputs and Outputs

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

d = 
1

g = 
2

p = 
3

Call the function again with no inputs or outputs.

variableNumInputAndOutput

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

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You cannot use varargin in the function definition for a top-level function in a MATLAB Function block or in a Stateflow^® chart that uses MATLAB^® as the action language.

• If you use varargin to define an argument to an entry-point function, the code generator produces a C/C++ function with a fixed number of input arguments. You specify the number of arguments at the time of code generation. See Specify Number of Input or Output Arguments to Entry-Point Functions (MATLAB Coder).

• You cannot write to varargin. If you want to write to input arguments, first copy the input arguments into a local variable.

• To index into varargin, use curly braces {}, not parentheses (). The index into varargin must be a constant at code generation time.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

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

R2024b: Support for multi-indexing input arguments into cell arrays in HDL Coder

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

[x, y] = varargin{1:2};

R2023a: Improved performance when specifying zero or more inputs

Specifying a variable number of input arguments using varargin shows improved performance. For example, in a file named timingTest.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 when varargin is empty.

• Empty varargin — Time this code by running timingTest(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 running timingTest(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.

R2022a: Generate HDL for MATLAB Function blocks with MATLAB Datapath architecture

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