[doc] comparisons page improved 41/20641/4
Samuel GOUGEON [Mon, 26 Nov 2018 19:42:53 +0000 (20:42 +0100)]
Change-Id: I12e56b35b79acf4b37abd4b03f58ce037b0ad019

scilab/modules/core/help/en_US/1_keywords/comparison.xml
scilab/modules/core/help/ja_JP/1_keywords/comparison.xml
scilab/modules/core/help/pt_BR/1_keywords/comparison.xml
scilab/modules/core/help/ru_RU/1_keywords/comparison.xml

index e9f84e4..1ce3a12 100644 (file)
@@ -1,5 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="comparison">
+<!--
+ *
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) - INRIA
+ * Copyright (C) 2018 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+          xml:lang="en" xml:id="comparison">
     <refnamediv>
         <refname>comparison</refname>
         <refpurpose>comparison, relational operators</refpurpose>
@@ -51,7 +68,8 @@
                 <term>The equality and inequality comparisons: </term>
                 <listitem>
                     <para>
-                        <literal>a==b</literal>, <literal>a~=b</literal> (or equivalently <literal>a&lt;&gt;b</literal>).
+                        <literal>a==b</literal>, <literal>a~=b</literal>
+                        (or equivalently <literal>a&lt;&gt;b</literal>).
                         These operators apply to any type of operands.
                     </para>
                 </listitem>
                     <para>
                         <literal>a&lt;b</literal>, <literal>a&lt;=b</literal>,
                         <literal>a&gt;b</literal>, <literal>a&gt;=b</literal>. These operators apply
-                        only to real floating point and integer arrays.
+                        only to integer and real numbers.
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
-        <para>The semantics of the comparison operators also depend on the operands types:</para>
+        <para>The result of the comparison operators also depends on the operands types:</para>
         <variablelist>
             <varlistentry>
                 <term>With array variables </term>
                 <listitem>
-                    <para> like floating point and integer arrays, logical arrays,
-                        string arrays, polynomial and rational arrays, handle arrays, lists... the following rules apply:
+                    <para>arrays of numbers, boolean arrays, string arrays, polynomial and rational
+                      arrays, handle arrays, lists... the following rules apply:
                     </para>
                     <itemizedlist>
                         <listitem>
                             <para>
-                                If <literal>a</literal> and <literal>b</literal> evaluates as arrays with same types
-                                and identical dimensions, the comparison is performed element by
-                                element and the result is an array of booleans of the same size.
+                                If <literal>a</literal> and <literal>b</literal> are arrays with same
+                                types and sizes, the comparison is performed element by
+                                element and the result is an array of booleans of the same sizes.
                             </para>
                         </listitem>
                         <listitem>
                             <para>
-                                If <literal>a</literal> and <literal>b</literal> evaluates as arrays
-                                with same types, but <literal>a</literal> or <literal>b</literal> is a scalar,
+                                If <literal>a</literal> and <literal>b</literal> have the same type
+                                and <literal>a</literal> or <literal>b</literal> is a scalar,
                                 then the scalar is compared with each element of the
                                 other array. The result is an array of booleans of the size of
                                 the non scalar operand.
                         </listitem>
                         <listitem>
                             <para>
-                                If <literal>a</literal> or <literal>b</literal> are arrays, but one of them
-                                is empty, then an equality or an inequality comparison is possible. In this case,
-                                the result is a scalar boolean.
+                                If <literal>a</literal> or <literal>b</literal> is an array while
+                                the other one is empty, then the result is a scalar boolean.
                             </para>
                         </listitem>
                         <listitem>
                             <para>
-                                In the others cases the result is the boolean <literal>%f</literal>
+                                In all other cases, the result is <literal>%F</literal>
                             </para>
                         </listitem>
                         <listitem>
                             <para>If the operand data types are different but "compatible" like
-                                floating points and integers, then a type conversion is performed before
-                                the comparison.
+                                decimal numbers and encoded integers, then a type conversion is
+                                performed before the comparison.
                             </para>
                         </listitem>
                     </itemizedlist>
                 </listitem>
             </varlistentry>
         </variablelist>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Polynomials</emphasis>:
+                        <literal>%s==%z</literal> returns <literal>%F</literal> :
+                        Two polynomials can't be considered as equal if they are not about the
+                        same variable.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Rationals</emphasis>:
+                        <literal>1/%s == 1/%z</literal> returns <literal>%F</literal> :
+                        Two rationals can't be equal if they are not about the same variable.
+                        In addition, the same rational may have different unnormalized forms
+                        that won't be considered as equal.
+                        For instance, <literal>2/(2*%z) == 1/%z</literal> returns <literal>%F</literal>,
+                        even in <literal>simp_mode(%T)</literal> simplification mode.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Sparse numerical matrix</emphasis>: any element-wise
+                        comparison with a full-encoded numerical array always returns a
+                        boolean sparse array. See examples.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Graphics identifiers</emphasis>: A graphic handle
+                        <literal>h1</literal> and its copy <literal>h2=h1</literal> will always
+                        stay equal, even if the graphics is changed through one of them.
+                        See examples.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
     <refsection>
         <title>Examples</title>
@@ -150,15 +205,192 @@ list(1,2,3)==1
 
 isequal(list(1,2,3),1)
 isequal(1:10,1)
+ ]]></programlisting>
+        <para/>
+        <para>
+            Comparisons with implicit conversion of type or encoding:
+        </para>
+        <programlisting role="example"><![CDATA[
+int32(1) == 1
+int32(1) < 1.5
+int32(1:5) < int8(3)
+1 == complex(1,0)
+1 > complex(1,0)  // still OK, but..
+1 > complex(1,1)  // => error: complex numbers not orderable
+ ]]></programlisting>
+    <screen><![CDATA[
+--> int32(1) == 1
+ ans  =
+  T
+
+--> int32(1) < 1.5
+ ans  =
+  T
+
+--> int32(1:5) < int8(3)
+ ans  =
+  T T F F F
 
-//comparison with type conversion
-int32(1)==1
-int32(1)<1.5
-int32(1:5)<int8(3)
-p=poly(0,'s','c')
-p==0
-p/poly(1,'s','c')==0
+--> 1 == complex(1,0)
+ ans  =
+  T
+
+--> 1 > complex(1,0)  // still OK, but..
+ ans  =
+  F
+
+--> 1 > complex(1,1)  // => error: complex numbers not orderable
+at line    11 of function %s_2_s ( SCI\modules\overloading\macros\%s_2_s.sci line 23 )
+Complex comparison not supported. Please define %s_2_s_custom() or check your code.
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with polynomials and rationals:
+        </para>
+        <programlisting role="example"><![CDATA[
+p = 0*%s
+p == 0
+r = p/(1+0*%s)
+r == 0
+r == p
+ps = (1-%s)^2, pz = (1-%z)^2
+ps == pz  // => %F : same variable required
  ]]></programlisting>
+    <screen><![CDATA[
+--> p = 0*%s
+ p  =
+   0
+
+--> p == 0
+ ans  =
+  T
+
+--> r = p/(1+0*%s)
+ r  =
+   0
+   --
+   1
+
+--> r == 0
+ ans  =
+  T
+
+--> r == p
+ ans  =
+  T
+
+--> ps = (1-%s)^2, pz = (1-%z)^2
+ ps  =
+             2
+   1  -2s +s
+ pz  =
+             2
+   1  -2z +z
+
+--> ps == pz  // => %F : same variable required
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with a sparse numerical matrix: All element-wise comparisons yield
+            a sparse-encoded result, <literal>%F</literal> otherwise.
+        </para>
+        <programlisting role="example"><![CDATA[
+sp = sparse([0 1 0 0 -2 0 4 0 0])
+sp < 0
+sp == 1
+sp >=       [2 3 -1 2 -4 0 3 1 0]
+sp == %i
+sp == list(3) // => %F
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sp = sparse([0 1 0 0 -2 0 4 0 0])
+ sp  =
+(  1,  9) sparse matrix
+(  1,  2)     1.
+(  1,  5)    -2.
+(  1,  7)     4.
+
+--> sp < 0
+ ans  =
+(  1,  9) sparse matrix
+(  1,  5)   T
+
+--> sp == 1
+ ans  =
+(  1,  9) sparse matrix
+(  1,  2)   T
+
+--> sp >= [2 3 -1 2 -4 0 3 1 0]
+ ans  =
+(  1,  9) sparse matrix
+(  1,  3)   T
+(  1,  5)   T
+(  1,  6)   T
+(  1,  7)   T
+(  1,  9)   T
+
+--> sp == %i
+ ans  =
+(  1,  9)False sparse matrix
+
+--> sp == list(3)  // object comparison => dense %F
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between graphics identifiers:
+        </para>
+        <programlisting role="example"><![CDATA[
+plot2d()
+e1 = gce();
+e2 = e1;    // e1 and e2 point to the same graphical object
+e2.tag
+e1.tag = "3 curves";
+e1 == e2
+e2.tag
+ ]]></programlisting>
+    <screen><![CDATA[
+--> e2.tag
+ ans  =
+
+--> e1.tag = "3 curves";
+--> e1 == e2
+ ans  =
+  T
+
+--> e2.tag
+ ans  =
+ 3 curves
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between functions aliases are possible:
+        </para>
+        <programlisting role="example"><![CDATA[
+sine = sin ;
+sine == sin
+sinus = sind ;
+sinus == sind
+sinus(0:90:360)
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sine = sin ;
+--> sine == sin
+ ans  =
+  T
+
+--> sinus = sind ;
+--> sinus == sind
+ ans  =
+  T
+
+--> sinus(0:90:360)
+ ans  =
+   0.   1.   0.  -1.   0.
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -170,11 +402,14 @@ p/poly(1,'s','c')==0
                 <link linkend="greater">greater</link>
             </member>
             <member>
-                <link linkend="boolean">boolean</link>
+                <link linkend="equal">equal</link>
             </member>
             <member>
                 <link linkend="isequal">isequal</link>
             </member>
+            <member>
+                <link linkend="boolean">boolean</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection role="history">
@@ -183,8 +418,16 @@ p/poly(1,'s','c')==0
             <revision>
                 <revnumber>6.0</revnumber>
                 <revdescription>
-                    <literal>~</literal> (not) priority is now higher than the comparisons one
-                    (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                    <itemizedlist>
+                        <listitem>
+                            <literal>~</literal> (not) priority is now higher than the comparisons
+                            one (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                        </listitem>
+                        <listitem>
+                            Complex numbers with a null imaginary part are now compared as real
+                            numbers.
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
index 5795107..272b6be 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
-
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="comparison">
-
+<!--
+ *
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) - INRIA
+ * Copyright (C) 2018 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+          xml:lang="ja" xml:id="comparison">
     <refnamediv>
-
         <refname>comparison</refname>
-
         <refpurpose>比較, 関係演算子</refpurpose>
-
     </refnamediv>
-
     <refsynopsisdiv>
-
         <title>呼出し手順</title>
-
         <synopsis>a==b
-
             a~=b or a&lt;&gt;b
-
             a&lt;b
-
             a&lt;=b
-
             a&gt;b
-
             a&gt;=b
-
         </synopsis>
-
     </refsynopsisdiv>
-
     <refsection>
-
         <title>引数</title>
-
         <variablelist>
-
             <varlistentry>
-
                 <term>a</term>
-
                 <listitem>
-
                     <para>
-
                         等値比較<literal>a==b</literal>, <literal>a~=b</literal>
-
                         <literal>a&lt;&gt;b</literal>の場合は任意の変数の型とすることができ,
-
                         順序が関連する比較<literal>a&lt;b</literal>,
-
                         <literal>a&lt;=b</literal>, <literal>a&gt;b</literal>,<literal>a&gt;=b</literal>
-
                         に関しては,浮動小数点の実数および整数の配列に制限されます.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>b</term>
-
                 <listitem>
-
                     <para>
-
                         等値比較 <literal>a==b</literal>, <literal>a~=b</literal>
-
                         <literal>a&lt; &gt; b</literal> の場合は任意の変数の型とすることができ,
-
                         順序が関連する比較
-
                         <literal>a&lt;b</literal>, <literal>a&lt;=b</literal>,
-
                         <literal>a&gt;b</literal>,<literal>a&gt;=b</literal>
-
                         に関しては,浮動小数点の実数および整数の配列に制限されます.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
     </refsection>
-
     <refsection>
-
         <title>説明</title>
-
         <para>2つの暮らすの演算士は区別する必要があります:</para>
-
         <variablelist>
-
             <varlistentry>
-
                 <term>等値および不等式比較: </term>
-
                 <listitem>
-
                     <para>
-
                         <literal>a==b</literal>, <literal>a~=b</literal> (または等価な <literal>a&lt;&gt;b</literal>).
-
                         これらの演算子は任意のオペランドの型に適用できます.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>順序が関連する比較: </term>
-
                 <listitem>
-
                     <para>
-
                         <literal>a&lt;b</literal>, <literal>a&lt;=b</literal>,
-
                         <literal>a&gt;b</literal>,<literal>a&gt;=b</literal>. これらの演算子は
-
                         浮動小数点の実数および整数の配列にのみ適用されます.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
         <para>比較演算子のセマンティクスもオペランドの型に依存します:</para>
-
         <variablelist>
-
             <varlistentry>
-
                 <term>配列変数の場合 </term>
-
                 <listitem>
-
                     <para>浮動小数点の実数および整数配列, 論理値配列,
-
                         文字列配列,多項式または有理配列,ハンドル配列,リスト...
-
                         のような配列変数の場合,以下の規則が適用されます:
-
                     </para>
-
                     <itemizedlist>
-
                         <listitem>
-
                             <para>
-
                                 <literal> a</literal>および <literal> b</literal> を
-
                                 同じ型,同じ次元の配列として評価する場合,
-
                                 要素毎の比較が行われ,
-
                                 結果は同じ次元の論理値の配列となります.
-
                             </para>
-
                         </listitem>
-
                         <listitem>
-
                             <para>
-
                                 If <literal> a</literal> および <literal> b</literal> が
-
                                 型は同じだが
-
                                 <literal> a</literal>または<literal> b</literal>が1行1列の配列の場合,
-
                                 このスカラーが別の配列の各要素と比較されます.
-
                                 この結果はスカラーでないオペランドの大きさの論理値の配列となります.
-
                             </para>
-
                         </listitem>
-
                         <listitem>
-
                             <para>その他の場合,
-
                                 結果は論理値 <literal> %f</literal> となります.
-
                             </para>
-
                         </listitem>
-
                         <listitem>
-
                             <para>オペランドのデータ型が異なるが浮動小数点と整数のように
-
                                 互換性がある場合,比較の前に型変換が行われます.
-
                             </para>
-
                         </listitem>
-
                     </itemizedlist>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>その他の型のオペランドの場合 </term>
-
                 <listitem>
-
                     <para>
-
                         <literal>function</literal>や
-
                         <literal>libraries</literal>のようなその他のオペランドの場合,
-
                         結果はオブジェクトが同じ場合に<literal>%t</literal>,
-
                         それ以外の場合に <literal>%f</literal> となります.
-
                     </para>
-
                     <para>互換性がないデータ型の間の等値比較は
-
                         <literal>%f</literal>を返します.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Polynomials</emphasis>:
+                        <literal>%s==%z</literal> returns <literal>%F</literal> :
+                        Two polynomials can't be considered as equal if they are not about the
+                        same variable.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Rationals</emphasis>:
+                        <literal>1/%s == 1/%z</literal> returns <literal>%F</literal> :
+                        Two rationals can't be equal if they are not about the same variable.
+                        In addition, the same rational may have different unnormalized forms
+                        that won't be considered as equal.
+                        For instance, <literal>2/(2*%z) == 1/%z</literal> returns <literal>%F</literal>,
+                        even in <literal>simp_mode(%T)</literal> simplification mode.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Sparse numerical matrix</emphasis>: any element-wise
+                        comparison with a full-encoded numerical array always returns a
+                        boolean sparse array. See examples.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Graphics identifiers</emphasis>: A graphic handle
+                        <literal>h1</literal> and its copy <literal>h2=h1</literal> will always
+                        stay equal, even if the graphics is changed through one of them.
+                        See examples.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
-
     <refsection>
-
         <title>例</title>
-
         <programlisting role="example"><![CDATA[
 //用途毎の比較
 (1:5)==3
@@ -269,67 +196,233 @@ sparse([1,2;4,5;3,10],[1,2,3]) == sparse([1,2;4,5;3,10],[1,2,3])
 'foo'==3
 1==[]
 list(1,2,3)==1
-
 isequal(list(1,2,3),1)
 isequal(1:10,1)
-
-//型変換を伴う比較
-int32(1)==1
-int32(1)<1.5
-int32(1:5)<int8(3)
-p=poly(0,'s','c')
-p==0
-p/poly(1,'s','c')==0
  ]]></programlisting>
-
+        <para/>
+        <para>
+            Comparisons with implicit conversion of type or encoding:
+        </para>
+        <programlisting role="example"><![CDATA[
+int32(1) == 1
+int32(1) < 1.5
+int32(1:5) < int8(3)
+1 == complex(1,0)
+1 > complex(1,0)  // still OK, but..
+1 > complex(1,1)  // => error: complex numbers not orderable
+ ]]></programlisting>
+    <screen><![CDATA[
+--> int32(1) == 1
+ ans  =
+  T
+
+--> int32(1) < 1.5
+ ans  =
+  T
+
+--> int32(1:5) < int8(3)
+ ans  =
+  T T F F F
+
+--> 1 == complex(1,0)
+ ans  =
+  T
+
+--> 1 > complex(1,0)  // still OK, but..
+ ans  =
+  F
+
+--> 1 > complex(1,1)  // => error: complex numbers not orderable
+at line    11 of function %s_2_s ( SCI\modules\overloading\macros\%s_2_s.sci line 23 )
+Complex comparison not supported. Please define %s_2_s_custom() or check your code.
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with polynomials and rationals:
+        </para>
+        <programlisting role="example"><![CDATA[
+p = 0*%s
+p == 0
+r = p/(1+0*%s)
+r == 0
+r == p
+ps = (1-%s)^2, pz = (1-%z)^2
+ps == pz  // => %F : same variable required
+ ]]></programlisting>
+    <screen><![CDATA[
+--> p = 0*%s
+ p  =
+   0
+
+--> p == 0
+ ans  =
+  T
+
+--> r = p/(1+0*%s)
+ r  =
+   0
+   --
+   1
+
+--> r == 0
+ ans  =
+  T
+
+--> r == p
+ ans  =
+  T
+
+--> ps = (1-%s)^2, pz = (1-%z)^2
+ ps  =
+             2
+   1  -2s +s
+ pz  =
+             2
+   1  -2z +z
+
+--> ps == pz  // => %F : same variable required
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with a sparse numerical matrix: All element-wise comparisons yield
+            a sparse-encoded result, <literal>%F</literal> otherwise.
+        </para>
+        <programlisting role="example"><![CDATA[
+sp = sparse([0 1 0 0 -2 0 4 0 0])
+sp < 0
+sp == 1
+sp >=       [2 3 -1 2 -4 0 3 1 0]
+sp == %i
+sp == list(3) // => %F
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sp = sparse([0 1 0 0 -2 0 4 0 0])
+ sp  =
+(  1,  9) sparse matrix
+(  1,  2)     1.
+(  1,  5)    -2.
+(  1,  7)     4.
+
+--> sp < 0
+ ans  =
+(  1,  9) sparse matrix
+(  1,  5)   T
+
+--> sp == 1
+ ans  =
+(  1,  9) sparse matrix
+(  1,  2)   T
+
+--> sp >= [2 3 -1 2 -4 0 3 1 0]
+ ans  =
+(  1,  9) sparse matrix
+(  1,  3)   T
+(  1,  5)   T
+(  1,  6)   T
+(  1,  7)   T
+(  1,  9)   T
+
+--> sp == %i
+ ans  =
+(  1,  9)False sparse matrix
+
+--> sp == list(3)  // object comparison => dense %F
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between graphics identifiers:
+        </para>
+        <programlisting role="example"><![CDATA[
+plot2d()
+e1 = gce();
+e2 = e1;    // e1 and e2 point to the same graphical object
+e2.tag
+e1.tag = "3 curves";
+e1 == e2
+e2.tag
+ ]]></programlisting>
+    <screen><![CDATA[
+--> e2.tag
+ ans  =
+
+--> e1.tag = "3 curves";
+--> e1 == e2
+ ans  =
+  T
+
+--> e2.tag
+ ans  =
+ 3 curves
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between functions aliases are possible:
+        </para>
+        <programlisting role="example"><![CDATA[
+sine = sin ;
+sine == sin
+正弦 = sind ;
+正弦 == sind
+正弦(0:90:360)
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sine = sin ;
+--> sine == sin
+ ans  =
+  T
+
+--> 正弦 = sind ;
+--> 正弦 == sind
+ ans  =
+  T
+
+--> 正弦(0:90:360)
+ ans  =
+   0.   1.   0.  -1.   0.
+]]></screen>
     </refsection>
-
     <refsection role="see also">
-
         <title>参照</title>
-
         <simplelist type="inline">
-
             <member>
-
                 <link linkend="less">less</link>
-
             </member>
-
             <member>
-
                 <link linkend="greater">greater</link>
-
             </member>
-
             <member>
-
-                <link linkend="boolean">boolean</link>
-
+                <link linkend="equal">equal</link>
             </member>
-
             <member>
-
                 <link linkend="isequal">isequal</link>
-
             </member>
-
+            <member>
+                <link linkend="boolean">boolean</link>
+            </member>
         </simplelist>
-
     </refsection>
-
     <refsection role="history">
         <title>履歴</title>
         <revhistory>
             <revision>
                 <revnumber>6.0</revnumber>
                 <revdescription>
-                    <literal>~</literal> (not) priority is now higher than the comparisons one
-                    (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                    <itemizedlist>
+                        <listitem>
+                            <literal>~</literal> (not) priority is now higher than the comparisons
+                            one (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                        </listitem>
+                        <listitem>
+                            Complex numbers with a null imaginary part are now compared as real
+                            numbers.
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
     </refsection>
-
-</refentry>
-
+</refentry>
\ No newline at end of file
index 9584f7d..8a67628 100644 (file)
@@ -1,5 +1,22 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="comparison" xml:lang="pt">
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ *
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) - INRIA
+ * Copyright (C) 2018 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="comparison" xml:lang="pt">
     <refnamediv>
         <refname>comparison</refname>
         <refpurpose>comparação, operadores relacionais</refpurpose>
                 </listitem>
             </varlistentry>
         </variablelist>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Polynomials</emphasis>:
+                        <literal>%s==%z</literal> returns <literal>%F</literal> :
+                        Two polynomials can't be considered as equal if they are not about the
+                        same variable.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Rationals</emphasis>:
+                        <literal>1/%s == 1/%z</literal> returns <literal>%F</literal> :
+                        Two rationals can't be equal if they are not about the same variable.
+                        In addition, the same rational may have different unnormalized forms
+                        that won't be considered as equal.
+                        For instance, <literal>2/(2*%z) == 1/%z</literal> returns <literal>%F</literal>,
+                        even in <literal>simp_mode(%T)</literal> simplification mode.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Sparse numerical matrix</emphasis>: any element-wise
+                        comparison with a full-encoded numerical array always returns a
+                        boolean sparse array. See examples.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Graphics identifiers</emphasis>: A graphic handle
+                        <literal>h1</literal> and its copy <literal>h2=h1</literal> will always
+                        stay equal, even if the graphics is changed through one of them.
+                        See examples.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
     <refsection>
         <title>Exemplos</title>
@@ -151,15 +206,192 @@ list(1,2,3)==1
 
 isequal(list(1,2,3),1)
 isequal(1:10,1)
+ ]]></programlisting>
+        <para/>
+        <para>
+            Comparisons with implicit conversion of type or encoding:
+        </para>
+        <programlisting role="example"><![CDATA[
+int32(1) == 1
+int32(1) < 1.5
+int32(1:5) < int8(3)
+1 == complex(1,0)
+1 > complex(1,0)  // still OK, but..
+1 > complex(1,1)  // => error: complex numbers not orderable
+ ]]></programlisting>
+    <screen><![CDATA[
+--> int32(1) == 1
+ ans  =
+  T
+
+--> int32(1) < 1.5
+ ans  =
+  T
+
+--> int32(1:5) < int8(3)
+ ans  =
+  T T F F F
+
+--> 1 == complex(1,0)
+ ans  =
+  T
+
+--> 1 > complex(1,0)  // still OK, but..
+ ans  =
+  F
+
+--> 1 > complex(1,1)  // => error: complex numbers not orderable
+at line    11 of function %s_2_s ( SCI\modules\overloading\macros\%s_2_s.sci line 23 )
+Complex comparison not supported. Please define %s_2_s_custom() or check your code.
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with polynomials and rationals:
+        </para>
+        <programlisting role="example"><![CDATA[
+p = 0*%s
+p == 0
+r = p/(1+0*%s)
+r == 0
+r == p
+ps = (1-%s)^2, pz = (1-%z)^2
+ps == pz  // => %F : same variable required
+ ]]></programlisting>
+    <screen><![CDATA[
+--> p = 0*%s
+ p  =
+   0
+
+--> p == 0
+ ans  =
+  T
+
+--> r = p/(1+0*%s)
+ r  =
+   0
+   --
+   1
 
-//comparação com conversão de tipo
-int32(1)==1
-int32(1)<1.5
-int32(1:5)<int8(3)
-p=poly(0,'s','c')
-p==0
-p/poly(1,'s','c')==0
+--> r == 0
+ ans  =
+  T
+
+--> r == p
+ ans  =
+  T
+
+--> ps = (1-%s)^2, pz = (1-%z)^2
+ ps  =
+             2
+   1  -2s +s
+ pz  =
+             2
+   1  -2z +z
+
+--> ps == pz  // => %F : same variable required
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons with a sparse numerical matrix: All element-wise comparisons yield
+            a sparse-encoded result, <literal>%F</literal> otherwise.
+        </para>
+        <programlisting role="example"><![CDATA[
+sp = sparse([0 1 0 0 -2 0 4 0 0])
+sp < 0
+sp == 1
+sp >=       [2 3 -1 2 -4 0 3 1 0]
+sp == %i
+sp == list(3) // => %F
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sp = sparse([0 1 0 0 -2 0 4 0 0])
+ sp  =
+(  1,  9) sparse matrix
+(  1,  2)     1.
+(  1,  5)    -2.
+(  1,  7)     4.
+
+--> sp < 0
+ ans  =
+(  1,  9) sparse matrix
+(  1,  5)   T
+
+--> sp == 1
+ ans  =
+(  1,  9) sparse matrix
+(  1,  2)   T
+
+--> sp >= [2 3 -1 2 -4 0 3 1 0]
+ ans  =
+(  1,  9) sparse matrix
+(  1,  3)   T
+(  1,  5)   T
+(  1,  6)   T
+(  1,  7)   T
+(  1,  9)   T
+
+--> sp == %i
+ ans  =
+(  1,  9)False sparse matrix
+
+--> sp == list(3)  // object comparison => dense %F
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between graphics identifiers:
+        </para>
+        <programlisting role="example"><![CDATA[
+plot2d()
+e1 = gce();
+e2 = e1;    // e1 and e2 point to the same graphical object
+e2.tag
+e1.tag = "3 curves";
+e1 == e2
+e2.tag
+ ]]></programlisting>
+    <screen><![CDATA[
+--> e2.tag
+ ans  =
+
+--> e1.tag = "3 curves";
+--> e1 == e2
+ ans  =
+  T
+
+--> e2.tag
+ ans  =
+ 3 curves
+]]></screen>
+        <para/>
+        <para>
+            Comparisons between functions aliases are possible:
+        </para>
+        <programlisting role="example"><![CDATA[
+sine = sin ;
+sine == sin
+seno = sind ;
+seno == sind
+seno(0:90:360)
  ]]></programlisting>
+    <screen><![CDATA[
+--> sine = sin ;
+--> sine == sin
+ ans  =
+  T
+
+--> seno = sind ;
+--> seno == sind
+ ans  =
+  T
+
+--> seno(0:90:360)
+ ans  =
+   0.   1.   0.  -1.   0.
+]]></screen>
     </refsection>
     <refsection>
         <title> Ver Também </title>
@@ -171,11 +403,14 @@ p/poly(1,'s','c')==0
                 <link linkend="greater">greater</link>
             </member>
             <member>
-                <link linkend="boolean">boolean</link>
+                <link linkend="equal">equal</link>
             </member>
             <member>
                 <link linkend="isequal">isequal</link>
             </member>
+            <member>
+                <link linkend="boolean">boolean</link>
+            </member>
         </simplelist>
     </refsection>
 
@@ -185,8 +420,16 @@ p/poly(1,'s','c')==0
             <revision>
                 <revnumber>6.0</revnumber>
                 <revdescription>
-                    <literal>~</literal> (not) priority is now higher than the comparisons one
-                    (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                    <itemizedlist>
+                        <listitem>
+                            <literal>~</literal> (not) priority is now higher than the comparisons
+                            one (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                        </listitem>
+                        <listitem>
+                            Complex numbers with a null imaginary part are now compared as real
+                            numbers.
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
index 505ac00..a2998cb 100644 (file)
@@ -1,5 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="comparison">
+<!--
+ *
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) - INRIA
+ * Copyright (C) 2018 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+          xml:lang="ru" xml:id="comparison">
     <refnamediv>
         <refname>сравнение</refname>
         <refpurpose>операторы сравнения, отношения</refpurpose>
                 </listitem>
             </varlistentry>
         </variablelist>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Полиномы</emphasis>:
+                        <literal>%s==%z</literal> возвращает <literal>%F</literal> :
+                        Два полинома не могут считаться равными, если они не относятся к одной и
+                        той же переменной.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Рациональные числа</emphasis>:
+                        <literal>1/%s == 1/%z</literal> возвращает <literal>%F</literal> :
+                        Два рациональных числа не могут быть равными если они не относятся к одной
+                        и той же переменной.
+                        Кроме того, одно и тоже рациональное число может иметь различные ненормированные
+                        формы, которые не могут считаться равными.
+                        Например, <literal>2/(2*%z) == 1/%z</literal> возвращат <literal>%F</literal>,
+                        даже в режиме упрощения <literal>simp_mode(%T)</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Разрежённая числовая матрица</emphasis>: любое поэлементное
+                        сравнение с полным числовым массивом всегда возвращает разрежённый массив логических
+                        значений. См. примеры.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <emphasis role="bold">Графические идентификаторы</emphasis>: графический дескриптор
+                        <literal>h1</literal> и его копия <literal>h2=h1</literal> всегда будут равными, даже
+                        если графические окна меняются с помощью одного из них. См. примеры.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
     <refsection>
         <title>Примеры</title>
@@ -144,15 +199,192 @@ list(1,2,3)==1
 
 isequal(list(1,2,3),1)
 isequal(1:10,1)
+ ]]></programlisting>
+        <para/>
+        <para>
+            Сравнения с явным преобразованием типов или кодирования:
+        </para>
+        <programlisting role="example"><![CDATA[
+int32(1) == 1
+int32(1) < 1.5
+int32(1:5) < int8(3)
+1 == complex(1,0)
+1 > complex(1,0)  // по-прежнему OK, однако...
+1 > complex(1,1)  // => ошибка: комплексные числа не упорядочены
+ ]]></programlisting>
+    <screen><![CDATA[
+--> int32(1) == 1
+ ans  =
+  T
+
+--> int32(1) < 1.5
+ ans  =
+  T
 
-//сравнение с преобразованием типов данных
-int32(1)==1
-int32(1)<1.5
-int32(1:5)<int8(3)
-p=poly(0,'s','c')
-p==0
-p/poly(1,'s','c')==0
+--> int32(1:5) < int8(3)
+ ans  =
+  T T F F F
+
+--> 1 == complex(1,0)
+ ans  =
+  T
+
+--> 1 > complex(1,0)  // по-прежнему OK, однако...
+ ans  =
+  F
+
+--> 1 > complex(1,1)  // => ошибка: комплексные числа не упорядочены
+at line    11 of function %s_2_s ( SCI\modules\overloading\macros\%s_2_s.sci line 23 )
+Комплексные числа не поддерживаются. Пожалуйста, определите %s_2_s_custom() или проверьте свой код.
+]]></screen>
+        <para/>
+        <para>
+            Сравнения с полиномами и рациональными числами:
+        </para>
+        <programlisting role="example"><![CDATA[
+p = 0*%s
+p == 0
+r = p/(1+0*%s)
+r == 0
+r == p
+ps = (1-%s)^2, pz = (1-%z)^2
+ps == pz  // => %F : требуются одни и те же переменные
  ]]></programlisting>
+    <screen><![CDATA[
+--> p = 0*%s
+ p  =
+   0
+
+--> p == 0
+ ans  =
+  T
+
+--> r = p/(1+0*%s)
+ r  =
+   0
+   --
+   1
+
+--> r == 0
+ ans  =
+  T
+
+--> r == p
+ ans  =
+  T
+
+--> ps = (1-%s)^2, pz = (1-%z)^2
+ ps  =
+             2
+   1  -2s +s
+ pz  =
+             2
+   1  -2z +z
+
+--> ps == pz  // => %F : требуются одни и те же переменные
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Сравнения с разрежёнными числовыми матрицами: все поэлементные сравнения выдают разрежённый
+            результат, в противном случае <literal>%F</literal>.
+        </para>
+        <programlisting role="example"><![CDATA[
+sp = sparse([0 1 0 0 -2 0 4 0 0])
+sp < 0
+sp == 1
+sp >=       [2 3 -1 2 -4 0 3 1 0]
+sp == %i
+sp == list(3) // => %F
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sp = sparse([0 1 0 0 -2 0 4 0 0])
+ sp  =
+(  1,  9) sparse matrix
+(  1,  2)     1.
+(  1,  5)    -2.
+(  1,  7)     4.
+
+--> sp < 0
+ ans  =
+(  1,  9) sparse matrix
+(  1,  5)   T
+
+--> sp == 1
+ ans  =
+(  1,  9) sparse matrix
+(  1,  2)   T
+
+--> sp >= [2 3 -1 2 -4 0 3 1 0]
+ ans  =
+(  1,  9) sparse matrix
+(  1,  3)   T
+(  1,  5)   T
+(  1,  6)   T
+(  1,  7)   T
+(  1,  9)   T
+
+--> sp == %i
+ ans  =
+(  1,  9)False sparse matrix
+
+--> sp == list(3)  // сравнение объектов => сжатая %F
+ ans  =
+  F
+]]></screen>
+        <para/>
+        <para>
+            Сравнения между графическими идентификаторами:
+        </para>
+        <programlisting role="example"><![CDATA[
+plot2d()
+e1 = gce();
+e2 = e1;    // точки e1 и e2 на оодном и томже графическом объекте
+e2.tag
+e1.tag = "3 curves";
+e1 == e2
+e2.tag
+ ]]></programlisting>
+    <screen><![CDATA[
+--> e2.tag
+ ans  =
+
+--> e1.tag = "3 curves";
+--> e1 == e2
+ ans  =
+  T
+
+--> e2.tag
+ ans  =
+ 3 curves
+]]></screen>
+        <para/>
+        <para>
+            Возможны сравнения псевдонимов функций:
+        </para>
+        <programlisting role="example"><![CDATA[
+sine = sin ;
+sine == sin
+синус = sind ;
+синус == sind
+синус(0:90:360)
+ ]]></programlisting>
+    <screen><![CDATA[
+--> sine = sin ;
+--> sine == sin
+ ans  =
+  T
+
+--> синус = sind ;
+--> синус == sind
+ ans  =
+  T
+
+--> синус(0:90:360)
+ ans  =
+   0.   1.   0.  -1.   0.
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
@@ -178,8 +410,15 @@ p/poly(1,'s','c')==0
             <revision>
                 <revnumber>6.0</revnumber>
                 <revdescription>
-                    <literal>~</literal> (отрицание) сейчас имеет приоритет выше, чем у операций сравнения
-                    (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                    <itemizedlist>
+                        <listitem>
+                            <literal>~</literal> (отрицание) сейчас имеет приоритет выше, чем у
+                            операций сравнения (<literal>==  ~=  &lt;  &lt;=  >=  ></literal>).
+                        </listitem>
+                        <listitem>
+                            Комплексные числа с нулевой мнимой частью теперь сравниваются как вещественные числа.
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>