Bad syntax in the help
[scilab.git] / scilab / modules / functions / help / en_US / varargin.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) ????-2008 - INRIA
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="varargin" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (Wed, 26 Mar 2008)
22     $</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>varargin</refname>
27
28     <refpurpose>variable numbers of arguments in an input argument
29     list</refpurpose>
30   </refnamediv>
31
32   <refsection>
33     <title>Description</title>
34
35     <para>A function whose last input argument is <literal>varargin</literal>
36     can be called with more input arguments than indicated in the input
37     argument list. The calling arguments passed form
38     <literal>varargin</literal> keyword onwards may then be retrieved within
39     the function in a list named <literal>varargin</literal>.</para>
40
41     <para>Suppose that <literal>varargin</literal> keyword is the
42     <literal>n</literal> th argument of the formal input argument list, then
43     if the function is called with less than <literal>n-1</literal> input
44     arguments the <literal>varargin</literal> list is not defined, if the
45     function is called with <literal>n-1</literal> arguments then
46     <literal>varargin</literal> list is an empty list.</para>
47
48     <para><literal>y = function ex(varargin)</literal> may be called with any
49     number of input arguments. Within function <literal>ex</literal> input
50     arguments may be retrieved in <literal>varargin(i)</literal>
51     ,<literal>i=1:length(varargin)</literal></para>
52
53     <para>If it is not the last input argument of a function,
54     <literal>varargin</literal> is a normal input argument name with no
55     special meaning.</para>
56
57     <para>The total number of actual input arguments is given by <link
58     linkend="argn(2)">argn(2)</link>.</para>
59   </refsection>
60
61   <refsection>
62     <title>Remark</title>
63
64     <para>Named argument syntax like <literal>foo(...,key=value) </literal> is
65     incompatible with the use of varargin. The reason is that the names (i.e.
66     keys) associated with values are not stored in the varargin list. Consider
67     for instance:</para>
68
69     <para>function
70     foo(varargin),disp([varargin(1),varargin(2)]),endfunction</para>
71
72     <para>foo(a=1,b=2)</para>
73
74     <para>Scilab answers: 1. 2.</para>
75
76     <para>foo(b=1,a=2)</para>
77
78     <para>Scilab answers: 1. 2.</para>
79
80     <para>Result is the same, but the arguments were inverted.</para>
81   </refsection>
82
83   <refsection>
84     <title>Examples</title>
85
86     <programlisting role="example">
87
88 deff('exampl(a,varargin)',['[lhs,rhs]=argn(0)'
89                           'if rhs&gt;=1 then disp(varargin),end'])
90 exampl(1)
91 exampl()
92 exampl(1,2,3)
93 l=list('a',%s,%t);
94 exampl(1,l(2:3))
95  
96   </programlisting>
97   </refsection>
98
99   <refsection>
100     <title>See Also</title>
101
102     <simplelist type="inline">
103       <member><link linkend="function">function</link></member>
104
105       <member><link linkend="varargout">varargout</link></member>
106
107       <member><link linkend="list">list</link></member>
108     </simplelist>
109   </refsection>
110 </refentry>