<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018, 2022 - 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.
 *
 -->
<!--  module: integer  -->
<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="fr" xml:id="int8">
    <refnamediv>
        <refname>int8 </refname>
        <refpurpose>conversion en entier sur 1 octet</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int16">
        <refname>int16</refname>
        <refpurpose>conversion en entier sur 2 octets</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int32">
        <refname>int32</refname>
        <refpurpose>conversion en entier sur 4 octets</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int64">
        <refname>int64</refname>
        <refpurpose>conversion en entier sur 8 octets</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint8">
        <refname>uint8 </refname>
        <refpurpose>conversion en entier non signé sur 1 octet</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint16">
        <refname>uint16</refname>
        <refpurpose>conversion en entier non signé sur 2 octets</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint32">
        <refname>uint32</refname>
        <refpurpose>conversion en entier non signé sur 4 octets</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint64">
        <refname>uint64</refname>
        <refpurpose>conversion en entier non signé sur 8 octets</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            y = int8(X)
            y = int16(X)
            y = int32(X)
            y = int64(X)
            y = uint8(X)
            y = uint16(X)
            y = uint32(X)
            y = uint64(X)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>X  </term>
                <listitem>
                    <para>
                        matrice de booléens, d'entiers encodés, ou de nombres décimaux réels ou complexes.
                        Matrice de strings représentant des grands nombres litéraux, pour <literal>int64</literal>
                        et <literal>uint64</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y  </term>
                <listitem>
                    <para>matrice d'entiers encodés sur 1, 2, 4 ou 8 octets. size(y) == size(X).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Convertit et stocke sous forme d'entiers. Ces types de données sont particulièrement
            intéressants pour stocker des images, de longs signaux, ...
        </para>
        <warning>
            <para>
                Lorsque des éléments de <varname>X</varname> ont une partie décimale non nulle,
                celle-ci est toujours tronquée (arrondie vers 0).<table></table>
                Exemple:
                <literal>int8([-3.6, -2.5, -1.4, 1.3, 3.5, 6.7]) // = [-3, -2, -1, 1, 3, 6]</literal>.
            </para>
            <para>
                Les valeurs de <varname>X</varname> hors de l'intervalle cible sont modulotées
                (non saturées). Exemples:
                <itemizedlist>
                    <listitem>
                        <literal>int8([127 128 129 130])  // = [127 -128 -127 -126]</literal>.
                    </listitem>
                    <listitem>
                        <literal>uint8([254 255 256 257]) // = [254 255 0 1]</literal>.
                    </listitem>
                </itemizedlist>
            </para>
            <para>
                -%inf est toujours converti en la borne inférieure de l'intervalle des valeurs
                possibles (voir ci-dessous).
            </para>
            <para>
                %inf est toujours converti en la borne supérieure de l'intervalle des valeurs
                possibles.
            </para>
            <para>%nan est toujours converti en 0.</para>
            <para>
                Si <varname>X</varname> est encodé en nombres complexes, les parties imaginaires
                de ses éléments sont ignorées. Seules les parties réelles converties sont retournées.
            </para>
            <para>[%f %t] est toujours converti en [0 1].</para>
        </warning>
        <warning>
            <para>
            <emphasis role="bold">Lecture de grands entiers litéraux avec <literal>int64()</literal>
            ou <literal>uint64()</literal> </emphasis>:
            Tout appel tel que <literal>int64(1000000000000000000)</literal> considère implicitement
            <literal>1000000000000000000</literal> comme un entier décimal dont la mantisse est
            encodée sur seulement
            53 bits &lt; 64 bits. Ainsi, cette mantisse sera ici tronquée, et l'entier obtenu après
            cette troncature ne sera en général pas celui fourni. Afin d'éviter cet effet, les grands
            entiers peuvent être fournis en chaine de caractères :
            <literal>int64("1000000000000000000")</literal> donnera l'entier attendu, sans perte de
            précision.
            Pour plus de détails concernant la précision pour les grands entiers, voir la page
            de la fonction <link linkend="double">double()</link> et un exemple ci-dessous.
            </para>
        </warning>
        <warning>
            La conversion de <literal>[]</literal> ne change rien : son type 1 est toujours
            conservé (type numérique décimal).
        </warning>
        <para>
            <table>
                <tr><th>Fonction</th><th>y dans</th><th align="left">=</th></tr>
                <tr><th>int8(X)</th>
                    <td>[- 2<superscript>7</superscript>,  2<superscript>7</superscript>-1]</td>
                    <td>[-128, 127]</td>
                </tr>
                <tr><th>int16(X)</th>
                    <td>[- 2<superscript>15</superscript>,  2<superscript>15</superscript>-1]</td>
                    <td>[-32768, 32767]</td>
                </tr>
                <tr><th>int32(X)</th>
                    <td>[- 2<superscript>31</superscript>,  2<superscript>31</superscript>-1]</td>
                    <td>[-2147483648, 2147483647]</td>
                </tr>
                <tr><th>int64(X)</th>
                    <td>[- 2<superscript>63</superscript>,  2<superscript>63</superscript>-1]</td>
                    <td>[-9223372036854775808, 9223372036854775807]</td>
                </tr>
                <tr><th>uint8(X)</th>
                    <td>[0, 2<superscript>8</superscript>-1]</td>
                    <td>[0, 255]</td>
                </tr>
                <tr><th>uint16(X)</th>
                    <td>[0, 2<superscript>16</superscript>-1]</td>
                    <td>[0, 65535]</td>
                </tr>
                <tr><th>uint32(X)</th>
                    <td>[0, 2<superscript>32</superscript>-1]</td>
                    <td>[0, 4294967295]</td>
                </tr>
                <tr><th>uint64(X)</th>
                    <td>[0, 2<superscript>64</superscript>-1]</td>
                    <td>[0, 18446744073709551615]</td>
                </tr>
            </table>
        </para>
    </refsection>
    <refsection role="examples">
        <title>Exemples</title>
        <para>
            Arrondis vers 0 et congruences ; valeurs spéciales :
        </para>
        <programlisting role="example"><![CDATA[
int8([-11.7 -8.5 -6.4  6.4 8.5 11.7])
int8([-130 -129 -128 -127 126 127 128 129])
a = -129 + 256*(-3:3)
int8(a)
int8([-%inf %inf %nan])
 ]]></programlisting>
    <screen><![CDATA[
--> int8([-11.7 -8.5 -6.4  6.4 8.5 11.7])
 ans  =
 -11 -8 -6  6  8  11

--> int8([-130 -129 -128 -127 126 127 128 129])
 ans  =
  126  127 -128 -127  126  127 -128 -127

--> a = -129 + 256*(-3:3)
 a  =
  -897.  -641.  -385.  -129.   127.   383.   639.

--> int8(a)
 ans  =
  127  127  127  127  127  127  127

--> int8([-%inf %inf %nan])
 ans  =
 -128  127  0
]]></screen>
    <para>
        À propos des effets de congruence (modulo) et des limites supérieures des encodages entiers
        non signés :
    </para>
    <programlisting role="example"><![CDATA[
uint8([-1 %inf])
uint16([-1 %inf])
uint32([-1 %inf])
uint64([-1 %inf])
 ]]></programlisting>
    <screen><![CDATA[
--> uint8([-1 %inf])
 ans  =
  255  255

--> uint16([-1 %inf])
 ans  =
  65535  65535

--> uint32([-1 %inf])
 ans  =
  4294967295  4294967295

--> uint64([-1 %inf])
 ans  =
  18446744073709551615  18446744073709551615
]]></screen>
    <para>
        Convertir de grands entiers encodés sur 64 bits en nombres décimaux altère leur valeur et
        dégrade leur précision relative :
    </para>
        <programlisting role="example"><![CDATA[
i = uint64(2)^63 - 600
i - uint64(double(i))
 ]]></programlisting>
    <screen><![CDATA[
--> i = uint64(2)^63 - 600
 i  =
  9223372036854775208

--> i - uint64(double(i))
 ans  =
  424
]]></screen>
    <para>
        Conversion de booléens et de nombres complexes :
    </para>
    <programlisting role="example"><![CDATA[
int8([%f %t])

int8(-10.2 + 3.4*%i)
uint8(-10.2 + 3.4*%i)
 ]]></programlisting>
    <screen><![CDATA[
--> int8([%f %t])
 ans  =
  0  1

--> int8(-10.2 + 3.4*%i)
 ans  =
 -10

--> uint8(-10.2 + 3.4*%i)
 ans  =
  246
]]></screen>
    <para>
        Lecture d'entiers int64 or uint64 supérieurs à 2^53, sans effet de troncature :
    </para>
    <programlisting role="example"><![CDATA[
a = [uint64(1000000000000001000) ; uint64("1000000000000001000")]
typeof(a)

a = [int64(-1000000000000001000) ; int64("-1000000000000001000")]
typeof(a)
 ]]></programlisting>
    <screen><![CDATA[
--> a = [uint64(1000000000000001000) ; uint64("1000000000000001000")]
 a  =
  1000000000000001024
  1000000000000001000

--> typeof(a)
 ans  =
  "uint64"

--> a = [int64(-1000000000000001000) ; int64("-1000000000000001000")]
 a  =
 -1000000000000001024
 -1000000000000001000

--> typeof(a)
 ans  =
  "int64"
]]></screen>
    <para>
        [] n'est pas convertible:
    </para>
    <programlisting role="example"><![CDATA[
i = uint16(3);
i(1,2) = 5.6
typeof(i)

i = uint16([])
i(1,2) = 2.3
typeof(i)
 ]]></programlisting>
    <screen><![CDATA[
--> i = uint16(3);
--> i(1,2) = 5.6
 i  =
  3  5

--> typeof(i)
 ans  =
 uint16


--> i = uint16([])
 i  =
    []

--> i(1,2) = 2.3
 i  =
   0.   2.3

--> typeof(i)
 ans  =
 constant
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="iconvert">iconvert</link>
            </member>
            <member>
                <link linkend="inttype">inttype</link>
            </member>
            <member>
                <link linkend="double">double</link>
            </member>
            <member>
                <link linkend="dec2bin">dec2bin</link>
            </member>
            <member>
                <link linkend="dec2base">dec2base</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Historique</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            int64() et uint64() ajoutées à Scilab.
                        </listitem>
                        <listitem>
                            Les nombres complexes sont désormais acceptés.
                        </listitem>
                        <listitem>
                            <table>
                                <tr><th>Ceci</th>               <th>vaut désormais</th><th>au lieu de</th></tr>
                                <tr><td>int8([-%inf, %inf])</td><td>[-128, 127]</td><td>[0, 0]</td></tr>
                                <tr><td>int16([-%inf, %inf])</td><td>[-32768, 32767]</td><td>[0, 0]</td></tr>
                                <tr><td>int32(%inf)</td>        <td>2147483647</td> <td>-2147483648</td></tr>
                                <tr><td>uint8(%inf)</td>        <td>255</td>        <td>0</td></tr>
                                <tr><td>uint16(%inf)</td>       <td>65535</td>      <td>0</td></tr>
                                <tr><td>uint32(%inf)</td>       <td>4294967295</td> <td>0</td></tr>
                            </table>
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.2</revnumber>
                <revdescription>
                    <literal>int64</literal> et <literal>uint64</literal> acceptent des strings
                    représentant des entiers litéraux pouvant être > 2<superscript>53</superscript>,
                    et les interprètent sans effet de troncature.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
