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

Create Function Wrapper

In a file in your working folder, create a wrapper to the plot function that plots a red line. The redplot function accepts a variable-length input argument list and returns a variable-length output argument list. It sets the line color to red, and forwards other input values to the plot function. This function wrapper enables you to pass redplot the same inputs as plot and not specify that the line color is red.

type redplot.m

function varargout = redplot(varargin)
    [varargout{1:nargout}] = plot(varargin{:},'Color',[1,0,0]);
end

Use redplot to create a line plot.

x = 0:pi/100:2*pi;
y = sin(x);
redplot(x,y)

Call redplot again, and specify input and output arguments to forward to the plot function.

h = redplot(x,y,'Marker','o','MarkerEdgeColor','green'); 

Extended Capabilities

C/C++ Code Generation

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

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.

HDL Code Generation

Generate Verilog and VHDL 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.

• To use varargin in a MATLAB function block that has the HDL block property Architecture set to MATLAB Datapath:

  • You can create cell arrays through only the use of varargin. You cannot use other initialization techniques, such as using the cell function or creating a cell array by using curly braces like cellArr = {1,2,3}.

  • You cannot multi-index into cell arrays. For example, this code snippet causes an error in HDL code generation.

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

Version History

Introduced before R2006a

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.