Validate Repeating Arguments

Repeating arguments are positional arguments that can be specified repeatedly as arguments. Declare repeating arguments in an arguments block that includes the Repeating attribute.

arguments (Repeating)
    arg1
    arg2
    ...
end

Functions can have one Repeating arguments block for inputs and one for outputs. A Repeating input arguments block can contain one or more repeating arguments, while a Repeating output arguments block can contain only one repeating argument.

A function that defines a Repeating arguments block can be called with zero or more occurrences of all the arguments in the block. If a call to a function includes repeating arguments, then all arguments in the Repeating arguments block must be included for each repetition.

For example, if a Repeating arguments block defines input arguments x and y, then each repetition must contain both x and y.

Repeating input arguments cannot specify default values and therefore cannot be optional. However, you can call the function without including any repeating arguments.

Functions must declare repeating input arguments after positional arguments and before name-value arguments. You cannot specify name-value arguments within a Repeating block. For information on name-value arguments, see Validate Name-Value Arguments.

In the function, each repeating argument becomes a cell array with the number of elements equal to the number of repeats passed in the function call. The validation is applied to each element of the cell array. If the function is called with zero occurrences of this argument, the cell array has a size of 1-by-0. That is, it is empty.

For example, this function declares a block of three repeating arguments, x, y, and option.

function [xCell,yCell,optionCell] = fRepeat(x,y,option)
    arguments (Repeating)
        x double
        y double
        option {mustBeMember(option,["linear","cubic"])}
    end
    
    % Function code
    % Return cell arrays
    xCell = x;
    yCell = y;
    optionCell = option;
end

You can call the function with no inputs or multiples of three inputs. MATLAB^® creates a cell array for each argument containing all the values passes for that argument. This call to fRepeat passes two sets of the three repeating arguments.

[xCell,yCell,optionCell] = fRepeat(1,2,"linear",3,4,"cubic")

xCell =

  1×2 cell array

    {[1]}    {[3]}


yCell =

  1×2 cell array

    {[2]}    {[4]}


optionCell =

  1×2 cell array

    {["linear"]}    {["cubic"]}

The following function accepts repeating arguments for x and y inputs in a Repeating arguments block. In the body of the function, the values specified as repeating arguments are available in the cell arrays x and y. This example interleaves the values of x and y to match the required input to the plot function: plot(x1,y1,…).

function myPlotRepeating(x,y)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
    end

    % Function code
    % Interleave x and y
    z = reshape([x;y],1,[]);

    % Call plot function
    if ~isempty(z)
        plot(z{:});
    end
end

Call this function with repeating pairs of arguments.

x1 = 1:10;
y1 = sin(x1);
x2 = 0:5;
y2 = sin(x2);
myPlotRepeating(x1,y1,x2,y2)

Avoid Using varargin for Repeating Arguments

Using varargin with functions that use argument validation is not recommended. If varargin is restricted in size or class in the repeating arguments block, then the restrictions apply to all values in varargin.

If you use varargin to support legacy code, it must be the only argument in a Repeating arguments block.

For example, this function defines two required positional arguments and varargin as the repeating argument.

function f(a, b, varargin)
    arguments
        a uint32
        b uint32
    end
    arguments (Repeating)
        varargin
    end
    
    % Function code
    ...
end