* Bug 15380 fixed: argn() page was unclear & uncomplete
[scilab.git] / scilab / modules / functions / help / fr_FR / 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="fr" xml:id="argn">
21     <refnamediv>
22         <refname>argn</refname>
23         <refpurpose>nombre effectif d'arguments d'entrée reçus / attendus en sortie d'une fonction</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Séquence d'appel</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>
40                     Nombre d'arguments de sortie attendus. Vaut 1 (au lieu de 0) si la fonction
41                     a été appelée sans argument de sortie.
42                 </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>rhs</term>
47                 <listitem>
48                 <para>
49                     Nombre d'arguments passés en entrée de la fonction Scilab considérée.
50                 </para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             Cette fonction est utilisée à l'intérieur d'une définition de fonction.
59             Elle donne le nombre effectif (au moment de l'appel) d'arguments d'entrée <varname>rhs</varname>
60             et de sortie <varname>lhs</varname>. Elle permet d'utiliser des arguments optionnels.
61         </para>
62         <warning>
63             Il n'est pas possible de savoir depuis une fonction Scilab si celle-ci a été appelée
64             sans aucun argument de sortie attendu. Le cas échéant, <varname>lhs</varname> vaut 1,
65             au lieu de 0.
66         </warning>
67         <warning>
68             L'existence d'un argument d'entrée nommé (hors de la portée d'un éventuel varargin)
69             peut être testée avec <literal>isdef(..,"l")</literal> de manière plus robuste
70             qu'en utilisant <literal>argn()</literal>. Un exemple figure ci-après.
71         </warning>
72     </refsection>
73     <refsection>
74         <title>Exemples</title>
75         <para>Exemples élémentaires :</para>
76         <programlisting role="example"><![CDATA[
77 function [res, res2] = test(a, b)
78   [lhs, rhs] = argn()
79   [res, res2] = ("abc", %pi);
80   disp([lhs rhs])  // <<<<<<<<<<<
81 endfunction
82
83 test();
84 test(4.321);
85 test(3, -1);
86 test(3, -1, a=0);
87 test(3, -1, c=8);
88
89 out1 = test();
90 [o1, o2] = test(%pi);
91  ]]></programlisting>
92     <screen><![CDATA[
93 --> test();
94    1.   0.
95
96 --> test(4.321);
97    1.   1.
98
99 --> test(3, -1);
100    1.   2.
101
102 --> test(3, -1, a=0);
103 Wrong number of input arguments.
104
105 --> test(3, -1, c=8);
106 Wrong number of input arguments.
107
108 --> out1 = test();
109    1.   0.
110
111 --> [o1, o2] = test(%pi);
112    2.   1.
113 ]]></screen>
114     <para/>
115     <para>Avec varargin ou/et varargout:</para>
116         <programlisting role="example"><![CDATA[
117 function [res, varargout] = test(a, varargin)
118   res = "abc";
119   varargout = list(%i);
120   [lhs, rhs] = argn()
121   disp([lhs rhs])  // <<<<<<<<<<<
122 endfunction
123
124 test();
125 test(4.321);
126 test(3, -1);
127 test(3, -1, a=0);
128 test(3, -1, 8);
129
130 out1 = test();
131 [o1, o2] = test(%pi);
132 [o1, o2, o3] = test(%pi);
133  ]]></programlisting>
134     <screen><![CDATA[
135 --> test();
136    1.   0.
137
138 --> test(4.321);
139    1.   1.
140
141 --> test(3, -1);
142    1.   2.
143
144 --> test(3, -1, a=0);
145    1.   3.
146
147 --> test(3, -1, 8);
148    1.   3.
149
150 --> out1 = test();
151    1.   0.
152
153 --> [o1, o2] = test(%pi);
154    2.   1.
155
156 --> [o1, o2, o3] = test(%pi);
157    3.   1.
158 ]]></screen>
159     <para/>
160     <para>Test robuste de l'existence d'un argument d'entrée:</para>
161         <programlisting role="example"><![CDATA[
162 function res = test(a, b, varargin)
163     res = ""
164     if isdef("a","l")
165         res = "a passed."
166     end
167     if isdef("b","l")
168         res = res + " b passed."
169     end
170     if isdef("c","l")
171         res = res + " c passed."
172     end
173 endfunction
174 clc
175 test()
176 test(4.321)
177 test(4.321, %z)
178 test(b=3)
179 test(c=3)
180 test(-1, c=3)
181 test(-1, a=2, c=3)
182 test(b=-1, a=2, c=3)
183  ]]></programlisting>
184     <screen><![CDATA[
185 --> test()
186  ans  =
187
188 --> test(4.321)
189  ans  =
190  a passed.
191
192 --> test(4.321, %z)
193  ans  =
194  a passed. b passed.
195
196 --> test(b=3)
197  ans  =
198   b passed.
199
200 --> test(c=3)
201  ans  =
202   c passed.
203
204 --> test(-1, c=3)
205  ans  =
206  a passed. c passed.
207
208 --> test(-1, a=2, c=3) // Les arguments passés via varargin sont toujours anonymes
209  ans  =
210  a passed.
211
212 --> test(b=-1, a=2, c=3)
213  ans  =
214  a passed. b passed.
215 ]]></screen>
216     <para/>
217     <para>Autre usage fréquent:</para>
218         <programlisting role="example"><![CDATA[
219 function concat = maFonction(nom,option)
220   [lhs, rhs] = argn()
221   if rhs <= 1 then
222      option = "mon argument optionnel";
223   end
224   if rhs == 0 then
225      error("Au moins un argument attendu");
226   end
227   concat = nom+" "+option;
228 endfunction
229  ]]></programlisting>
230     </refsection>
231     <refsection role="see also">
232         <title>Voir aussi</title>
233         <simplelist type="inline">
234             <member>
235                 <link linkend="isdef">isdef</link>
236             </member>
237             <member>
238                 <link linkend="varargin">varargin</link>
239             </member>
240             <member>
241                 <link linkend="varargout">varargout</link>
242             </member>
243             <member>
244                 <link linkend="macrovar">macrovar</link>
245             </member>
246             <member>
247                 <link linkend="function">function</link>
248             </member>
249         </simplelist>
250     </refsection>
251 </refentry>