[ast] allow _iRetCount == 0 in gateways
[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. Is set to 1 when no output
40                 argument is expected.
41                 </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>rhs</term>
46                 <listitem>
47                 <para>Number of Right-Hand-Side input arguments provided in the function call.
48                 </para>
49                 </listitem>
50             </varlistentry>
51         </variablelist>
52     </refsection>
53     <refsection>
54         <title>Description</title>
55         <para>
56             This function is used inside a function definition.
57             It gives the number of actual inputs arguments (<varname>rhs</varname>)
58             and output arguments (<varname>lhs</varname>) passed to the function when the function is
59             called. It is usually used in function definitions to deal with
60             optional arguments.
61         </para>
62         <warning>
63             Testing the existence of a named input argument with <literal>isdef(..,"l")</literal>
64             is more robust that with <literal>argn()</literal>. Please see examples.
65         </warning>
66     </refsection>
67     <refsection>
68         <title>Examples</title>
69         <para>Simple examples:</para>
70         <programlisting role="example"><![CDATA[
71 function [res, res2] = test(a, b)
72   [lhs, rhs] = argn()
73   [res, res2] = ("abc", %pi);
74   disp([lhs rhs])  // <<<<<<<<<<<
75 endfunction
76
77 test();
78 test(4.321);
79 test(3, -1);
80 test(3, -1, a=0);
81 test(3, -1, c=8);
82
83 out1 = test();
84 [o1, o2] = test(%pi);
85  ]]></programlisting>
86     <screen><![CDATA[
87 --> test();
88    1.   0.
89
90 --> test(4.321);
91    1.   1.
92
93 --> test(3, -1);
94    1.   2.
95
96 --> test(3, -1, a=0);
97 Wrong number of input arguments.
98
99 --> test(3, -1, c=8);
100 Wrong number of input arguments.
101
102 --> out1 = test();
103    1.   0.
104
105 --> [o1, o2] = test(%pi);
106    2.   1.
107 ]]></screen>
108     <para/>
109     <para>With varargin and varargout:</para>
110         <programlisting role="example"><![CDATA[
111 function [res, varargout] = test(a, varargin)
112   res = "abc";
113   varargout = list(%i);
114   [lhs, rhs] = argn()
115   disp([lhs rhs])  // <<<<<<<<<<<
116 endfunction
117
118 test();
119 test(4.321);
120 test(3, -1);
121 test(3, -1, a=0);
122 test(3, -1, 8);
123
124 out1 = test();
125 [o1, o2] = test(%pi);
126 [o1, o2, o3] = test(%pi);
127  ]]></programlisting>
128     <screen><![CDATA[
129 --> test();
130    1.   0.
131
132 --> test(4.321);
133    1.   1.
134
135 --> test(3, -1);
136    1.   2.
137
138 --> test(3, -1, a=0);
139    1.   3.
140
141 --> test(3, -1, 8);
142    1.   3.
143
144 --> out1 = test();
145    1.   0.
146
147 --> [o1, o2] = test(%pi);
148    2.   1.
149
150 --> [o1, o2, o3] = test(%pi);
151    3.   1.
152 ]]></screen>
153     <para/>
154     <para>Robust test of the existence of input arguments:</para>
155         <programlisting role="example"><![CDATA[
156 function res = test(a, b, varargin)
157     res = ""
158     if isdef("a","l")
159         res = "a passed."
160     end
161     if isdef("b","l")
162         res = res + " b passed."
163     end
164     if isdef("c","l")
165         res = res + " c passed."
166     end
167 endfunction
168 clc
169 test()
170 test(4.321)
171 test(4.321, %z)
172 test(b=3)
173 test(c=3)
174 test(-1, c=3)
175 test(-1, a=2, c=3)
176 test(b=-1, a=2, c=3)
177  ]]></programlisting>
178     <screen><![CDATA[
179 --> test()
180  ans  =
181
182 --> test(4.321)
183  ans  =
184  a passed.
185
186 --> test(4.321, %z)
187  ans  =
188  a passed. b passed.
189
190 --> test(b=3)
191  ans  =
192   b passed.
193
194 --> test(c=3)
195  ans  =
196   c passed.
197
198 --> test(-1, c=3)
199  ans  =
200  a passed. c passed.
201
202 --> test(-1, a=2, c=3) // argins in varargin are/become always anonymous
203  ans  =
204  a passed.
205
206 --> test(b=-1, a=2, c=3)
207  ans  =
208  a passed. b passed.
209 ]]></screen>
210     <para/>
211     <para>Another usage:</para>
212     <programlisting role="example"><![CDATA[
213 function concat = myOwnFunction(name,optional)
214   [lhs, rhs] = argn()
215   if rhs <= 1 then
216      optional="my Optional value";
217   end
218   if rhs == 0 then
219      error("Expect at least one argument");
220   end
221   concat=name+" "+optional;
222 endfunction
223  ]]></programlisting>
224     </refsection>
225     <refsection role="see also">
226         <title>See also</title>
227         <simplelist type="inline">
228             <member>
229                 <link linkend="isdef">isdef</link>
230             </member>
231             <member>
232                 <link linkend="varargin">varargin</link>
233             </member>
234             <member>
235                 <link linkend="varargout">varargout</link>
236             </member>
237             <member>
238                 <link linkend="macrovar">macrovar</link>
239             </member>
240             <member>
241                 <link linkend="function">function</link>
242             </member>
243         </simplelist>
244     </refsection>
245 </refentry>