* Bug 15380 fixed: argn() page was unclear & uncomplete
[scilab.git] / scilab / modules / functions / help / pt_BR / argn.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
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:ns4="http://www.w3.org/1999/xhtml"
19         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20         xmlns:scilab="http://www.scilab.org" xml:id="argn" xml:lang="pt">
21     <refnamediv>
22         <refname>argn</refname>
23         <refpurpose>número de argumentos na chamada de uma função</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Seqüência de Chamamento</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>Parâmetros</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>Descrição</title>
55         <para>Esta função é usada dentro da definição de uma função. Ela fornece
56             os números de parâmetros de entrada <literal>rhs</literal> e saída
57             <literal>lhs</literal> passados à função quando esta é chamada. Geralmente
58             é usada em definições de funções para lidar com parâmetros
59             opcionais.
60         </para>
61         <warning>
62             There is no way to detect whether a Scilab function is called without expected
63             output argument. In this case, <varname>lhs</varname> returns 1.
64         </warning>
65         <warning>
66             Testing the existence of a named input argument with <literal>isdef(..,"l")</literal>
67             is more robust that with <literal>argn()</literal>. Please see examples.
68         </warning>
69     </refsection>
70     <refsection>
71         <title>Exemplos</title>
72         <para>Exemplos simples :</para>
73         <programlisting role="example"><![CDATA[
74 function [res, res2] = test(a, b)
75   [lhs, rhs] = argn()
76   [res, res2] = ("abc", %pi);
77   disp([lhs rhs])  // <<<<<<<<<<<
78 endfunction
79
80 test();
81 test(4.321);
82 test(3, -1);
83 test(3, -1, a=0);
84 test(3, -1, c=8);
85
86 out1 = test();
87 [o1, o2] = test(%pi);
88  ]]></programlisting>
89     <screen><![CDATA[
90 --> test();
91    1.   0.
92
93 --> test(4.321);
94    1.   1.
95
96 --> test(3, -1);
97    1.   2.
98
99 --> test(3, -1, a=0);
100 Wrong number of input arguments.
101
102 --> test(3, -1, c=8);
103 Wrong number of input arguments.
104
105 --> out1 = test();
106    1.   0.
107
108 --> [o1, o2] = test(%pi);
109    2.   1.
110 ]]></screen>
111     <para/>
112     <para>Com varargin e varargout:</para>
113         <programlisting role="example"><![CDATA[
114 function [res, varargout] = test(a, varargin)
115   res = "abc";
116   varargout = list(%i);
117   [lhs, rhs] = argn()
118   disp([lhs rhs])  // <<<<<<<<<<<
119 endfunction
120
121 test();
122 test(4.321);
123 test(3, -1);
124 test(3, -1, a=0);
125 test(3, -1, 8);
126
127 out1 = test();
128 [o1, o2] = test(%pi);
129 [o1, o2, o3] = test(%pi);
130  ]]></programlisting>
131     <screen><![CDATA[
132 --> test();
133    1.   0.
134
135 --> test(4.321);
136    1.   1.
137
138 --> test(3, -1);
139    1.   2.
140
141 --> test(3, -1, a=0);
142    1.   3.
143
144 --> test(3, -1, 8);
145    1.   3.
146
147 --> out1 = test();
148    1.   0.
149
150 --> [o1, o2] = test(%pi);
151    2.   1.
152
153 --> [o1, o2, o3] = test(%pi);
154    3.   1.
155 ]]></screen>
156     <para/>
157     <para>Teste robusto da existência de argumentos de entrada:</para>
158         <programlisting role="example"><![CDATA[
159 function res = test(a, b, varargin)
160     res = ""
161     if isdef("a","l")
162         res = "a passed."
163     end
164     if isdef("b","l")
165         res = res + " b passed."
166     end
167     if isdef("c","l")
168         res = res + " c passed."
169     end
170 endfunction
171 clc
172 test()
173 test(4.321)
174 test(4.321, %z)
175 test(b=3)
176 test(c=3)
177 test(-1, c=3)
178 test(-1, a=2, c=3)
179 test(b=-1, a=2, c=3)
180  ]]></programlisting>
181     <screen><![CDATA[
182 --> test()
183  ans  =
184
185 --> test(4.321)
186  ans  =
187  a passed.
188
189 --> test(4.321, %z)
190  ans  =
191  a passed. b passed.
192
193 --> test(b=3)
194  ans  =
195   b passed.
196
197 --> test(c=3)
198  ans  =
199   c passed.
200
201 --> test(-1, c=3)
202  ans  =
203  a passed. c passed.
204
205 --> test(-1, a=2, c=3) // argins in varargin are/become always anonymous
206  ans  =
207  a passed.
208
209 --> test(b=-1, a=2, c=3)
210  ans  =
211  a passed. b passed.
212 ]]></screen>
213     <para/>
214     <para>Outro uso:</para>
215     <programlisting role="example"><![CDATA[
216 function concat = myOwnFunction(name,optional)
217   [lhs, rhs] = argn()
218   if rhs <= 1 then
219      optional="my Optional value";
220   end
221   if rhs == 0 then
222      error("Expect at least one argument");
223   end
224   concat=name+" "+optional;
225 endfunction
226  ]]></programlisting>
227     </refsection>
228     <refsection role="see also">
229         <title>Ver Também</title>
230         <simplelist type="inline">
231             <member>
232                 <link linkend="isdef">isdef</link>
233             </member>
234             <member>
235                 <link linkend="varargin">varargin</link>
236             </member>
237             <member>
238                 <link linkend="varargout">varargout</link>
239             </member>
240             <member>
241                 <link linkend="macrovar">macrovar</link>
242             </member>
243             <member>
244                 <link linkend="function">function</link>
245             </member>
246         </simplelist>
247     </refsection>
248 </refentry>