<?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>
    </refnamediv>
    <refsynopsisdiv>
        <title> Seqüência de Chamamento </title>
        <synopsis>a==b
            a~=b ou a&lt;&gt;b
            a&lt;b
            a&lt;=b
            a&gt;b
            a&gt;=b
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title> Parâmetros </title>
        <variablelist>
            <varlistentry>
                <term>a</term>
                <listitem>
                    <para>qualquer tipo de variável para comparações de igualdade
                        <literal>a==b</literal>, <literal>a~=b</literal>
                        <literal>a&lt;&gt;b</literal> e restrita a arrays de pontos
                        flutuantes reais e inteiros para comparações relacionadas à ordem
                        <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>qualquer tipo de variável para comparações de igualdade
                        <literal>a==b</literal>, <literal>a~=b</literal> <literal>a&lt; &gt;
                            b
                        </literal>
                        erestrita a arrays de ponto flutuantes reais e inteiros
                        para comparações relacionadas à ordem <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>Descrição</title>
        <para> Duas classes de operadores devem ser distinguidas:</para>
        <variablelist>
            <varlistentry>
                <term>Comparações de igualdade e desigualdade:</term>
                <listitem>
                    <para>
                        <literal>a==b</literal>, <literal>a~=b</literal> (ou de modo
                        equivalente <literal>a&lt;&gt;b</literal>). Estes operadores se
                        aplicam a quaisquer tipos de operandos.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Comparações de ordem:</term>
                <listitem>
                    <para>
                        <literal>a&lt;b</literal>, <literal>a&lt;=b</literal>,
                        <literal>a&gt;b</literal>,<literal>a&gt;=b</literal>. Estes
                        operadores se aplicam apenas a arrays de pontos flutuantes reais e
                        inteiros.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>A semântica dos operadores de comparação também depende dos tipos de
            operandos:
        </para>
        <variablelist>
            <varlistentry>
                <term>Com variáveis arrays</term>
                <listitem>
                    <para>como arrays de pontos flutuantes ou inteiros, arrays lógicos,
                        arrays de strings, arrays de polinômios ou razões de polinômios,
                        arrays de manipuladores, listas,... o seguinte se aplica:
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                Se <literal> a</literal> e <literal> b</literal> são
                                avaliados como arrays do mesmo tipo e dimensões idênticas, a
                                comparação é realizada elemento a elemento e o resultado é um
                                array de booleanos da comparação.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                Se <literal> a</literal> e <literal> b</literal> são
                                avaliados como arrays do mesmo tipo, mas <literal> a</literal>
                                ou <literal> b</literal> é um array 1 por 1, o elemento é
                                comparado com cada elemento do outro array. O resultado é um
                                array de booleanos com o tamanho do operando não-escalar.
                            </para>
                        </listitem>
                        <listitem>
                            <para>Em outros casos, o resultado é o booleano <literal>
                                    %f
                                </literal>
                            </para>
                        </listitem>
                        <listitem>
                            <para>Se os tipos de dados dos operandos são diferentes, mas
                                "compatíveis", como pontos flutuantes e inteiros, uma conversão
                                de tipo é realizada antes da comparação.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Com outros tipos de operandos</term>
                <listitem>
                    <para>
                        como <literal>function</literal>,
                        <literal>libraries</literal>, o resultado é <literal> %t</literal>
                        se os objetos são idênticos e <literal> %f</literal> em outros
                        casos.
                    </para>
                    <para>Comparação de igualdade entre operandos com tipos de dados
                        incompatíveis retorna <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>Exemplos</title>
        <programlisting role="example"><![CDATA[
//comparações elemento a elemento
(1:5)==3
(1:5)<=4
(1:5)<=[1 4 2 3 0]
1<[]
list(1,2,3)~=list(1,3,3)
"foo"=="bar"
sparse([1,2;4,5;3,10],[1,2,3]) == sparse([1,2;4,5;3,10],[1,2,3])

//comparações objeto a objeto
(1:10)==[4,3]
'foo'==3
1==[]
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

--> 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>
        <simplelist type="inline">
            <member>
                <link linkend="less">less</link>
            </member>
            <member>
                <link linkend="greater">greater</link>
            </member>
            <member>
                <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>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <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>
