<?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" version="5.0-subset Scilab"
        xml:lang="en" xml:id="int8">
    <refnamediv>
        <refname>int8</refname>
        <refpurpose> conversion to one byte integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int16">
        <refname>int16</refname>
        <refpurpose> conversion to 2 bytes integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int32">
        <refname>int32</refname>
        <refpurpose> conversion to 4 bytes integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="int64">
        <refname>int64</refname>
        <refpurpose> conversion to 8 bytes integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint8">
        <refname>uint8</refname>
        <refpurpose> conversion to one byte unsigned integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint16">
        <refname>uint16</refname>
        <refpurpose> conversion to 2 bytes unsigned integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint32">
        <refname>uint32</refname>
        <refpurpose> conversion to 4 bytes unsigned integer representation</refpurpose>
    </refnamediv>
    <refnamediv xml:id="uint64">
        <refname>uint64</refname>
        <refpurpose> conversion to 8 bytes unsigned integer representation</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</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>
                        matrix of booleans, of encoded integers, or of decimal real or complex numbers.
                        Matrix of strings representing literal big integers for <literal>int64</literal>
                        and <literal>uint64</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        matrix of integers encoded on 1, 2, 4 or 8 bytes. Its sizes are X ones.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            These functions convert and store data to one, two, four, or eight bytes integers.
            These data types are especially useful to store big objects such as images,
            long signals,...
        </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>
        </warning>
        <warning>
            <para>
            <emphasis role="bold">Reading big literal integers with int64 or uint64</emphasis>:
            Any input like <literal>int64(1000000000000000000)</literal> implicitly considers
            <literal>1000000000000000000</literal> as a decimal integer whose mantissa is encoded
            with only 53 bits
            &lt; 64 bits. Hence, this mantissa is most often truncated, and the encoded integer
            we get after the floating point truncation is not the input one.
            To avoid this effect, the integer can be provided as a string:
            <literal>int64("1000000000000000000")</literal> returns the expected integer, without
            loss of accuracy.
            For more details about truncation effect for big integers, 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>Examples</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>
        Reading literal int64 or uint64 integers bigger than 2^53,
        without floating point truncation effect:
    </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>
        [] 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>See also</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>History</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>
            <revision>
                <revnumber>6.1.2</revnumber>
                <revdescription>
                    <literal>int64</literal> and <literal>uint64</literal> are extended to strings
                    to read big integers > 2<superscript>53</superscript> without truncation.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
