<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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:ns4="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="int8" xml:lang="pt">
    <refnamediv>
        <refname>int8</refname>
        <refpurpose>conversão para representação de inteiro de 1 byte
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="int16">
        <refname>int16</refname>
        <refpurpose>conversão para representação de inteiro de 2 bytes
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="int32">
        <refname>int32</refname>
        <refpurpose>conversão para representação de inteiro de 4 bytes
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="int64">
        <refname>int64</refname>
        <refpurpose>conversão para representação de inteiro de 8 bytes
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint8">
        <refname>uint8</refname>
        <refpurpose>conversão para representação de inteiro de 1 byte sem sinal
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint16">
        <refname>uint16</refname>
        <refpurpose>conversão para representação de inteiro de 2 bytes sem sinal
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint32">
        <refname>uint32</refname>
        <refpurpose>conversão para representação de inteiro de 4 bytes sem sinal
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint64">
        <refname>uint32</refname>
        <refpurpose>conversão para representação de inteiro de 8 bytes sem sinal
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</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>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>X</term>
                <listitem>
                    <para>
                        matriz de booleanos, de inteiros codificados, ou de números reais ou
                        complexos decimais.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                    <para>
                        matriz de inteiros codificados em 1, 2, 4 ou 8 bytes. Seus tamanhos são os
                        de X.
                    </para>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>Converte e armazena dados em interos de 1, 2 ou 4 bytes. Estes tipos
            de dados são especialmente úteis para armazenar objetos grandes como
            imagens, sinais longos,...
        </para>
        <warning>
            <para>
                If some <varname>X</varname> decimal components have a fractional part, it is
                always trimmed to 0.<table></table>
                Example:
                <literal>int8([-3.6, -2.5, -1.4, 1.3, 3.5, 6.7]) // = [-3, -2, -1, 1, 3, 6]</literal>.
            </para>
            <para>
                Values of <varname>X</varname> components that are out of the targeted interval are
                wrapped (not saturated). Examples:
                <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 is always converted into the lower bound of the interval (see below).</para>
            <para>%inf is always converted into the upper bound of the interval (see below).</para>
            <para>%nan is always converted into 0.</para>
            <para>If <varname>X</varname> is complex encoded, imaginary parts are ignored.
                Only the real parts are converted and returned.
            </para>
            <para>[%f %t] is always converted into [0 1].</para>
            <para>
            Converting big int64 or uint64 integers into decimal numbers may change them
            and downgrade their relative accuracy. Indeed, int64|uint64 integers are encoded over
            63|64 bits, while the mantissa of decimal numbers is encoded over 53 bits only.
            For more details, please refer to the <link linkend="double">double()</link> page.
            </para>
        </warning>
        <warning>
            Converting <literal>[]</literal> always keeps it as is, of type 1 (decimal type).
        </warning>
        <para>
            <table>
                <tr><th>Function</th><th>y in</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>Exemplos</title>
        <para>
            Rounding to 0 and wrapping, and special values:
        </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>
        About wrapping and upper bounds of unsigned integers:
    </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>
        Converting 64-bits integers into decimal numbers downgrades their accuracy:
    </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>
        Converting booleans and complex numbers:
    </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>
        [] is not 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>Ver Também</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>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            int64() and uint64() added to Scilab.
                        </listitem>
                        <listitem>
                            Complex input numbers are now accepted.
                        </listitem>
                        <listitem>
                            <table>
                                <tr><th>This</th>               <th>is now</th>     <th>instead of</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>
        </revhistory>
    </refsection>
</refentry>
