update CHANGES and help pages after c1dbf528 67/21267/4
Clement David [Wed, 29 Jan 2020 16:34:49 +0000 (17:34 +0100)]
Change-Id: Ic66374254472001351eada1514ddcaa601e72675

scilab/CHANGES.md
scilab/modules/functions/help/en_US/argn.xml
scilab/modules/functions/help/fr_FR/argn.xml

index 47b025e..78a59a8 100644 (file)
@@ -33,6 +33,7 @@ In summary, the main new features are:
    - complex numbers are aligned for matrices
    - numbers (IEEE 754 double) are not rounded
 * importgui function has been added to easily interface csvRead
+* function calls with zero output arguments can be detected with `argn`
 
 
 Installation
@@ -175,9 +176,14 @@ Xcos
 * `CURVE_c` settings did not always display a window.
 * Exporting all layers from a diagram will generate one unique file per layer.
 
-API modification
+API/ABI modification
 ----------------
 
+* Functions could return zeros arguments, the following gateway functions have been updated:
+ - on APIv5 C `CheckOutputArgument(ctx, min, max)` the `min` argument should be set to `0` if needed.
+ - on APIv5 C `getNbOutputArgument(ctx)` the return value could be `0`
+ - on APIv6 C++ the `_iRetCount` argument value could be `0`.
+* On APIv6 C++, a virtual method has been added on internal types which break the ABI. Toolboxes need to be recompiled.
 
 Obsolete functions or features
 ------------------------------
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>
index 0d22f2b..2140244 100644 (file)
@@ -37,8 +37,7 @@
                 <term>lhs</term>
                 <listitem>
                 <para>
-                    Nombre d'arguments de sortie attendus. Vaut 1 (au lieu de 0) si la fonction
-                    a été appelée sans argument de sortie.
+                       Nombre d'arguments de sortie attendus. Vaut <code>0</code> si la fonction a été appelée sans argument de sortie.
                 </para>
                 </listitem>
             </varlistentry>
@@ -84,73 +83,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>Avec varargin ou/et 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>Test robuste de l'existence d'un argument d'entrée:</para>
         <programlisting role="example"><![CDATA[
@@ -176,38 +140,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) // Les arguments passés via varargin sont toujours anonymes
- ans  =
- a passed.
-
---> test(b=-1, a=2, c=3)
- ans  =
- a passed. b passed.
-]]></screen>
     <para/>
     <para>Autre usage fréquent:</para>
         <programlisting role="example"><![CDATA[
@@ -243,4 +175,8 @@ endfunction
             </member>
         </simplelist>
     </refsection>
+    <refsection>
+           <title>History</title>
+           <revhistory><revision><revnumber>6.1.0</revnumber><revremark>L'argument <code>lhs</code> est assigné à zero si appelé sans argument de sortie.</revremark></revision></revhistory>
+    </refsection>
 </refentry>