update CHANGES and help pages after c1dbf528
[scilab.git] / scilab / modules / functions / help / en_US / argn.xml
index 91e270f..f5130a1 100644 (file)
@@ -36,8 +36,7 @@
             <varlistentry>
                 <term>lhs</term>
                 <listitem>
-                <para>Number of expected Left-Hand-Side output arguments. Is set to 1 when no output
-                argument is expected.
+                       <para>Number of expected Left-Hand-Side output arguments assigned at the function call.
                 </para>
                 </listitem>
             </varlistentry>
         <title>Description</title>
         <para>
             This function is used inside a function definition.
-            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.
+            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.
         </para>
         <warning>
             Testing the existence of a named input argument with <literal>isdef(..,"l")</literal>
             is more robust that with <literal>argn()</literal>. Please see examples.
         </warning>
+        <para>
+            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.
+        </para>
     </refsection>
     <refsection>
         <title>Examples</title>
@@ -83,73 +82,38 @@ test(3, -1, c=8);
 out1 = test();
 [o1, o2] = test(%pi);
  ]]></programlisting>
-    <screen><![CDATA[
---> test();
-   1.   0.
-
---> test(4.321);
-   1.   1.
-
---> test(3, -1);
-   1.   2.
-
---> test(3, -1, a=0);
-Wrong number of input arguments.
-
---> test(3, -1, c=8);
-Wrong number of input arguments.
-
---> out1 = test();
-   1.   0.
-
---> [o1, o2] = test(%pi);
-   2.   1.
-]]></screen>
     <para/>
     <para>With varargin and varargout:</para>
         <programlisting role="example"><![CDATA[
-function [res, varargout] = test(a, varargin)
+function [varargout] = disp_argn(varargin)
+  varargout = list("abc",%i);
+  [lhs, rhs] = argn()
+  disp([lhs rhs])  // <<<<<<<<<<<
+endfunction
+
+function [res, varargout] = disp_argn_with_args(a, varargin)
   res = "abc";
   varargout = list(%i);
   [lhs, rhs] = argn()
   disp([lhs rhs])  // <<<<<<<<<<<
 endfunction
 
-test();
-test(4.321);
-test(3, -1);
-test(3, -1, a=0);
-test(3, -1, 8);
-
-out1 = test();
-[o1, o2] = test(%pi);
-[o1, o2, o3] = test(%pi);
+// varargin
+disp_argn(1);
+disp_argn_with_args(1);
+disp_argn(1, 2);
+disp_argn_with_args(1, 2);
+disp_argn(1, 2, 3);
+disp_argn_with_args(1, 2, 3);
+
+// varargout
+out1 = disp_argn();
+out1 = disp_argn_with_args();
+[o1, o2] = disp_argn();
+[o1, o2] = disp_argn_with_args();
+[o1, o2, o3] = disp_argn();
+[o1, o2, o3] = disp_argn_with_args();
  ]]></programlisting>
-    <screen><![CDATA[
---> test();
-   1.   0.
-
---> test(4.321);
-   1.   1.
-
---> test(3, -1);
-   1.   2.
-
---> test(3, -1, a=0);
-   1.   3.
-
---> test(3, -1, 8);
-   1.   3.
-
---> out1 = test();
-   1.   0.
-
---> [o1, o2] = test(%pi);
-   2.   1.
-
---> [o1, o2, o3] = test(%pi);
-   3.   1.
-]]></screen>
     <para/>
     <para>Robust test of the existence of input arguments:</para>
         <programlisting role="example"><![CDATA[
@@ -175,38 +139,6 @@ test(-1, c=3)
 test(-1, a=2, c=3)
 test(b=-1, a=2, c=3)
  ]]></programlisting>
-    <screen><![CDATA[
---> test()
- ans  =
-
---> test(4.321)
- ans  =
- a passed.
-
---> test(4.321, %z)
- ans  =
- a passed. b passed.
-
---> test(b=3)
- ans  =
-  b passed.
-
---> test(c=3)
- ans  =
-  c passed.
-
---> test(-1, c=3)
- ans  =
- a passed. c passed.
-
---> test(-1, a=2, c=3) // argins in varargin are/become always anonymous
- ans  =
- a passed.
-
---> test(b=-1, a=2, c=3)
- ans  =
- a passed. b passed.
-]]></screen>
     <para/>
     <para>Another usage:</para>
     <programlisting role="example"><![CDATA[
@@ -233,7 +165,7 @@ endfunction
             </member>
             <member>
                 <link linkend="varargout">varargout</link>
-            </member>
+       </member>
             <member>
                 <link linkend="macrovar">macrovar</link>
             </member>
@@ -242,4 +174,8 @@ endfunction
             </member>
         </simplelist>
     </refsection>
+    <refsection>
+           <title>History</title>
+           <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>
+    </refsection>
 </refentry>