Merge remote-tracking branch 'origin/6.1'
[scilab.git] / scilab / modules / functions / help / en_US / argn.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  * Copyright (C) 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
19         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
20         xml:lang="en" xml:id="argn">
21     <refnamediv>
22         <refname>argn</refname>
23         <refpurpose>Returns the actual number of input/output arguments in a function call</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             [lhs, rhs] = argn()
29             lhs = argn(1)
30             rhs = argn(2)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection role="arguments">
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>lhs</term>
38                 <listitem>
39                         <para>Number of expected Left-Hand-Side output arguments assigned at the function call.
40                 </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>rhs</term>
45                 <listitem>
46                 <para>Number of Right-Hand-Side input arguments provided in the function call.
47                 </para>
48                 </listitem>
49             </varlistentry>
50         </variablelist>
51     </refsection>
52     <refsection>
53         <title>Description</title>
54         <para>
55             This function is used inside a function definition.
56             It gives the number of actual inputs arguments (<varname>rhs</varname>) and output arguments (<varname>lhs</varname>) passed to the function when the function is called. It is usually used in function definitions to deal with optional arguments.
57         </para>
58         <warning>
59             Testing the existence of a named input argument with <literal>isdef(..,"l")</literal>
60             is more robust that with <literal>argn()</literal>. Please see examples.
61         </warning>
62         <para>
63             When the caller function has either no output argument or only <varname>varargout</varname>, the (<varname>lhs</varname>) is set to <code>0</code>. Otherwise, the number of expected arguments is set.
64         </para>
65     </refsection>
66     <refsection>
67         <title>Examples</title>
68         <para>Simple examples:</para>
69         <programlisting role="example"><![CDATA[
70 function [res, res2] = test(a, b)
71   [lhs, rhs] = argn()
72   [res, res2] = ("abc", %pi);
73   disp([lhs rhs])  // <<<<<<<<<<<
74 endfunction
75
76 test();
77 test(4.321);
78 test(3, -1);
79 test(3, -1, a=0);
80 test(3, -1, c=8);
81
82 out1 = test();
83 [o1, o2] = test(%pi);
84  ]]></programlisting>
85     <para/>
86     <para>With varargin and varargout:</para>
87         <programlisting role="example"><![CDATA[
88 function [varargout] = disp_argn(varargin)
89   varargout = list("abc",%i);
90   [lhs, rhs] = argn()
91   disp([lhs rhs])  // <<<<<<<<<<<
92 endfunction
93
94 function [res, varargout] = disp_argn_with_args(a, varargin)
95   res = "abc";
96   varargout = list(%i);
97   [lhs, rhs] = argn()
98   disp([lhs rhs])  // <<<<<<<<<<<
99 endfunction
100
101 // varargin
102 disp_argn(1);
103 disp_argn_with_args(1);
104 disp_argn(1, 2);
105 disp_argn_with_args(1, 2);
106 disp_argn(1, 2, 3);
107 disp_argn_with_args(1, 2, 3);
108
109 // varargout
110 out1 = disp_argn();
111 out1 = disp_argn_with_args();
112 [o1, o2] = disp_argn();
113 [o1, o2] = disp_argn_with_args();
114 [o1, o2, o3] = disp_argn();
115 [o1, o2, o3] = disp_argn_with_args();
116  ]]></programlisting>
117     <para/>
118     <para>Robust test of the existence of input arguments:</para>
119         <programlisting role="example"><![CDATA[
120 function res = test(a, b, varargin)
121     res = ""
122     if isdef("a","l")
123         res = "a passed."
124     end
125     if isdef("b","l")
126         res = res + " b passed."
127     end
128     if isdef("c","l")
129         res = res + " c passed."
130     end
131 endfunction
132 clc
133 test()
134 test(4.321)
135 test(4.321, %z)
136 test(b=3)
137 test(c=3)
138 test(-1, c=3)
139 test(-1, a=2, c=3)
140 test(b=-1, a=2, c=3)
141  ]]></programlisting>
142     <para/>
143     <para>Another usage:</para>
144     <programlisting role="example"><![CDATA[
145 function concat = myOwnFunction(name,optional)
146   [lhs, rhs] = argn()
147   if rhs <= 1 then
148      optional="my Optional value";
149   end
150   if rhs == 0 then
151      error("Expect at least one argument");
152   end
153   concat=name+" "+optional;
154 endfunction
155  ]]></programlisting>
156     </refsection>
157     <refsection role="see also">
158         <title>See also</title>
159         <simplelist type="inline">
160             <member>
161                 <link linkend="isdef">isdef</link>
162             </member>
163             <member>
164                 <link linkend="varargin">varargin</link>
165             </member>
166             <member>
167                 <link linkend="varargout">varargout</link>
168         </member>
169             <member>
170                 <link linkend="macrovar">macrovar</link>
171             </member>
172             <member>
173                 <link linkend="function">function</link>
174             </member>
175         </simplelist>
176     </refsection>
177     <refsection>
178             <title>History</title>
179             <revhistory><revision><revnumber>6.1.0</revnumber><revremark>The <code>lhs</code> argument is set to zero when the caller function has no output assignement.</revremark></revision></revhistory>
180     </refsection>
181 </refentry>