<?xml version="1.0" encoding="UTF-8"?>
<!--
 *
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2019 - 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:ns3="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="assert_checkequal" xml:lang="en">
    <refnamediv>
        <refname>assert_checkequal</refname>
        <refpurpose>Check that computed and expected are equal.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            assert_checkequal ( computed , expected )
            flag = assert_checkequal ( computed , expected )
            [flag,errmsg] = assert_checkequal ( computed , expected )
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term>computed:</term>
                <listitem>
                    <para> the computed result</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>expected :</term>
                <listitem>
                    <para> the expected result</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag :</term>
                <listitem>
                    <para> a boolean, %t if computed is equal to expected, %f if not</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>errmsg :</term>
                <listitem>
                    <para>
                        a string, the error message. If flag==%t, then errormsg=="".
                        If flag==%f, then errmsg contains the error message.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Performs silently if <varname>computed</varname> and <varname>expected</varname> are equal.
        </para>
        <para>
            For complex numbers: We compare first the real parts. In case of equality, we compare
            the imaginary parts.
        </para>
        <para>
            Matching Nan values are always considered equal.
        </para>
        <para>
            <literal>1/%z</literal> and <literal>2/(2*%z)</literal> are not equal: For the time
            being, Scilab does not normalize equivalent rationals.
        </para>
        <para>
            In containers, matching <literal>void</literal> elements are considered equal.
        </para>
        <para>
            If the comparison shows that computed is equal to expected,
            <itemizedlist>
                <listitem>
                    <para>if the errmsg output variable is not used, an error is generated,</para>
                </listitem>
                <listitem>
                    <para>if the errmsg output variable is used, no error is generated.</para>
                </listitem>
            </itemizedlist>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            Tests with success:
        </para>
        <programlisting role="example"><![CDATA[
assert_checkequal ( %T , %T );
[flag , errmsg] = assert_checkequal ( [%T %F], [%T %F] );
assert_checkequal ( %nan , %nan );
c = complex(1, %nan)
assert_checkequal (c, c);
assert_checkequal ( sparse(%nan) , sparse(%nan) );
assert_checkequal ( 2:$-1, 2:$-1 );

assert_checkequal ( ["abc" "" ascii([9 10 13])],  ["abc" "" ascii([9 10 13])] );
assert_checkequal ( [gdf(), gda()], [gdf(), gda()]);

assert_checkequal ( list() , list() );
assert_checkequal ( list(1,,3), list(1,,3) );
assert_checkequal ( list(1,,list(,4)), list(1,,list(,4)) );
assert_checkequal ( list(%nan,,7) , list(%nan,,7) );

sine = sin;
assert_checkequal ( sin, sine );
cosinus = cosd;
assert_checkequal ( cosinus, cosd );
assert_checkequal( iolib, iolib );
   ]]></programlisting>
        <para>
            Tests with failure:
        </para>
        <programlisting role="example"><![CDATA[
assert_checkequal ( %F , %T );
flag = assert_checkequal ( %F , %T );
// No error produced :
[flag , errmsg] = assert_checkequal ( %F , %T )

assert_checkequal ( [1 2], [3 4] )
assert_checkequal ( 1 , [2 3] )
assert_checkequal ( 1 , "b" )
assert_checkequal ( "b", "B" )
assert_checkequal ( 1+%s, 1+%z )
assert_checkequal ( 1/%s, 2/(2*%s) )

assert_checkequal (list(2,,7), list(2,%F,8));
assert_checkequal ( [gdf(), gda()], [gdf(), gdf()] );
assert_checkequal ( sind, cosd );
assert_checkequal ( iolib, corelib );
   ]]></programlisting>
   <screen><![CDATA[
...
--> assert_checkequal (list(2,,7), list(2,%F,8));
at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
at line   178 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 190 )

assert_checkequal: Assertion failed: expected(2)= F  while computed(2)= (void)

--> assert_checkequal ( [gdf(), gda()], [gdf(), gdf()] );
at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
at line   178 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 190 )

assert_checkequal: Assertion failed: expected(2)= Figure(uid:55)  while computed(2)= Axes(uid:85)

--> assert_checkequal ( sind, cosd );
at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
at line    82 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 94 )

assert_checkequal: Assertion failed: expected= cosd()  while computed= sind()

--> assert_checkequal ( iolib, corelib );
at line    22 of function assert_generror   ( SCI\modules\..\assert_generror.sci line 33 )
at line    95 of function assert_checkequal ( SCI\modules\..\assert_checkequal.sci line 107 )

assert_checkequal: Assertion failed: expected= lib@SCI\modules\core\macros\  while ..
                                     computed= lib@SCI\modules\io\macros\
]]></screen>
    </refsection>
    <refsection>
        <title>Bibliography</title>
        <para>"Automated Software Testing for Matlab", Steven Eddins, 2009</para>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revdescription>Function introduced
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    <itemizedlist>
                      <listitem>
                          The comparison of two implicit lists, Scilab functions, Scilab libraries,
                          built-in functions or graphic handles is now always possible and properly
                          done.
                      </listitem>
                      <listitem>
                          In two lists, void and Nan elements are now supported, and matching ones
                          are considered as equal.
                      </listitem>
                      <listitem>
                          Nan are now supported in input sparse matrices and are considered as equal.
                      </listitem>
                      <listitem>
                          When the test fails while inputs are arrays, the message now indicates
                          the index of the first mismatching element.
                      </listitem>
                  </itemizedlist>
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revdescription>
                    Matching NaN or void elements in simple or nested containers are now considered equal.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
