<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ????-2008 - INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="varargin" xml:lang="en">
    <refnamediv>
        <refname>varargin</refname>
        <refpurpose>variable number of arguments in an input argument list
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            A function whose last input argument is <literal>varargin</literal>
            can be called with more input arguments than indicated in the input
            argument list. The calling arguments passed form
            <literal>varargin</literal> keyword onwards may then be retrieved within
            the function in a list named <literal>varargin</literal>.
        </para>
        <para>
            Suppose that <literal>varargin</literal> keyword is the
            <literal>n</literal>-th argument of the formal input argument list, then
            if the function is called with less than <literal>n-1</literal> input
            arguments the <literal>varargin</literal> list is not defined, if the
            function is called with <literal>n-1</literal> arguments then
            <literal>varargin</literal> list is an empty list.
        </para>
        <para>
            <literal>function y = ex(varargin)</literal> may be called with any
            number of input arguments. Within function <literal>ex</literal> input
            arguments may be retrieved in <literal>varargin(i)</literal>,
            <literal>i=1:length(varargin)</literal>.
        </para>
        <para>
            If it is not the last input argument of a function,
            <literal>varargin</literal> is a normal input argument name with no
            special meaning.
        </para>
        <para>
            The total number of actual input arguments is given by <code>argn(2)</code>.
        </para>
    </refsection>
    <refsection>
        <title>Remark</title>
        <para>
            Named argument syntax like <literal>foo(...,key=value)</literal> is incompatible
            with the use of <literal>varargin</literal>. The reason is that the names (i.e.
            keys) associated with values are not stored in the <literal>varargin</literal> list.
            Consider for instance:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
function foo(varargin)
    disp([varargin(1),varargin(2)])
endfunction
        ]]></programlisting>
        <screen><![CDATA[--> foo(a=1, b=2)
 1.    2.
--> foo(b=1, a=2)
 1.    2.
]]></screen>
        <para>
            Result is the same, but the arguments were inverted.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
function exampl(a,varargin)
    [lhs,rhs]=argn(0)
    if rhs>=1 then
        disp(varargin)
    end
endfunction

exampl(1)
exampl()
exampl(1,2,3)
l=list('a',%s,%t);
exampl(1,l(2:3))
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="varargout">varargout</link>
            </member>
            <member>
                <link linkend="argn">argn</link>
            </member>
            <member>
                <link linkend="function">function</link>
            </member>
            <member>
                <link linkend="list">list</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
