<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * 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: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="signed_zero">
    <refnamediv>
        <refname>signed zero -0</refname>
        <refpurpose>Processing of -0 versus 0</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            The binary representation of decimal numbers is such that one bit over 64 (= 8 bytes) is
            dedicated to the sign of the mantissa. This is true for any decimal number, that
            can be symetrically positive or negative. This also applies to the zero value.
        </para>
        <para>
            It is possible to force to minus the sign of zero by using the unary minus
            and writting <literal>-0</literal>.
        </para>
        <para>
            Most of operations and functions do not take the sign of zero into account, but there
            are some exceptions. For instance, the division and atan() do not yield the same
            results with 0 and -0.
        </para>
        <para>
            Common interesting cases are illustrated in the following examples.
        </para>
        <note>
            As 0, -0 is not stored in sparse-encoded matrices, and so is ignored.
        </note>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            0 and -0 are distinguished:
        </para>
        <programlisting role="example"><![CDATA[
bitstring([0 ; -0])
[1/0 1/-0]
a = - 0 - 0;    1 / a
a = - 0 + (-0); 1 / a
1 / (0*(-0))
1 / prod([-0 1])
1 ./ ((-0)^[1 2 3])
[atan(0,0), atan(0,-0)]
     ]]></programlisting>
        <screen><![CDATA[
--> bitstring([0 ; -0])
 ans  =
!0000000000000000000000000000000000000000000000000000000000000000  !
!1000000000000000000000000000000000000000000000000000000000000000  !

--> [1/0 1/-0]
 ans  =
   Inf  -Inf

--> a = - 0 - 0; 1 / a
 ans  =
  -Inf

--> a = - 0 + (-0); 1 / a
 ans  =
  -Inf

--> 1 / (0*(-0))
 ans  =
  -Inf

--> 1 / prod([-0 1])
 ans  =
  -Inf

--> 1 ./ ((-0)^[1 2 3])
 ans  =
  -Inf   Inf  -Inf

--> [atan(0,0), atan(0,-0)]
 ans  =
   0.   3.1415927
]]></screen>
        <para/>
        <para>
        .. but + 0 wins:
        </para>
        <programlisting role="example"><![CDATA[
a = - 0 + 0; 1 / a
     ]]></programlisting>
        <screen><![CDATA[
--> a = - 0 + 0; 1 / a
 ans  =
   Inf
]]></screen>
        <para/>
        <para>
        0 and -0 are NOT distinguished:
        </para>
        <programlisting role="example"><![CDATA[
[sign(-0), 1/sign(-0)]
sign(0)==sign(-0)
[ isequal(0,-0), 0==-0,  -0<0,  0>-0 ]
1 / sin(-0)
     ]]></programlisting>
        <screen><![CDATA[
--> [sign(-0), 1/sign(-0)]
 ans  =
   0.   Inf

--> sign(0)==sign(-0)
 ans  =
  T

--> [ isequal(0,-0), 0==-0,  -0<0,  0>-0 ]
 ans  =
  T T F F

--> 1 / sin(-0)
 ans  =
   Inf
]]></screen>
        <para/>
        <para>
            The sparse encoding ignores -0 as it does for 0:
        </para>
        <programlisting role="example"><![CDATA[
sparse([-0 0 1])
1 / sparse(-0)
     ]]></programlisting>
        <screen><![CDATA[
--> sparse([-0 0 1])
 ans  =
(  1,  3) sparse matrix
(  1,  3)     1.

--> 1 / sparse(-0)
 ans  =
    Inf
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="percentinf">%inf</link>
            </member>
            <member>
                <link linkend="zeros">zeros</link>
            </member>
            <member>
                <link linkend="sparse">sparse</link>
            </member>
            <member>
                <link linkend="number_properties">number_properties</link>
            </member>
            <member>
                <ulink url="https://en.wikipedia.org/wiki/Signed_zero">Signed zero on Wikipedia</ulink>
            </member>
        </simplelist>
    </refsection>
</refentry>
