* Bug 15431 fixed [doc]: empty [] better documented
[scilab.git] / scilab / modules / integer / help / en_US / int8.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
19         xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab"
20         xml:lang="en" xml:id="int8">
21     <refnamediv>
22         <refname>int8</refname>
23         <refpurpose> conversion to one byte integer representation</refpurpose>
24     </refnamediv>
25     <refnamediv xml:id="int16">
26         <refname>int16</refname>
27         <refpurpose> conversion to 2 bytes integer representation</refpurpose>
28     </refnamediv>
29     <refnamediv xml:id="int32">
30         <refname>int32</refname>
31         <refpurpose> conversion to 4 bytes integer representation</refpurpose>
32     </refnamediv>
33     <refnamediv xml:id="int64">
34         <refname>int64</refname>
35         <refpurpose> conversion to 8 bytes integer representation</refpurpose>
36     </refnamediv>
37     <refnamediv xml:id="uint8">
38         <refname>uint8</refname>
39         <refpurpose> conversion to one byte unsigned integer representation</refpurpose>
40     </refnamediv>
41     <refnamediv xml:id="uint16">
42         <refname>uint16</refname>
43         <refpurpose> conversion to 2 bytes unsigned integer representation</refpurpose>
44     </refnamediv>
45     <refnamediv xml:id="uint32">
46         <refname>uint32</refname>
47         <refpurpose> conversion to 4 bytes unsigned integer representation</refpurpose>
48     </refnamediv>
49     <refnamediv xml:id="uint64">
50         <refname>uint64</refname>
51         <refpurpose> conversion to 8 bytes unsigned integer representation</refpurpose>
52     </refnamediv>
53     <refsynopsisdiv>
54         <title>Syntax</title>
55         <synopsis>
56             y = int8(X)
57             y = int16(X)
58             y = int32(X)
59             y = int64(X)
60             y = uint8(X)
61             y = uint16(X)
62             y = uint32(X)
63             y = uint64(X)
64         </synopsis>
65     </refsynopsisdiv>
66     <refsection>
67         <title>Arguments</title>
68         <variablelist>
69             <varlistentry>
70                 <term>X</term>
71                 <listitem>
72                     <para>
73                         matrix of booleans, of encoded integers, or of decimal real or complex numbers.
74                     </para>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>y</term>
79                 <listitem>
80                     <para>
81                         matrix of integers encoded on 1, 2, 4 or 8 bytes. Its sizes are X ones.
82                     </para>
83                 </listitem>
84             </varlistentry>
85         </variablelist>
86     </refsection>
87     <refsection>
88         <title>Description</title>
89         <para>
90             These functions convert and store data to one, two, four, or eight bytes integers.
91             These data types are especially useful to store big objects such as images,
92             long signals,...
93         </para>
94         <warning>
95             <para>
96                 If some <varname>X</varname> decimal components have a fractional part, it is
97                 always trimmed to 0.<table></table>
98                 Example:
99                 <literal>int8([-3.6, -2.5, -1.4, 1.3, 3.5, 6.7]) // = [-3, -2, -1, 1, 3, 6]</literal>.
100             </para>
101             <para>
102                 Values of <varname>X</varname> components that are out of the targeted interval are
103                 wrapped (not saturated). Examples:
104                 <itemizedlist>
105                     <listitem>
106                         <literal>int8([127 128 129 130])  // = [127 -128 -127 -126]</literal>.
107                     </listitem>
108                     <listitem>
109                         <literal>uint8([254 255 256 257]) // = [254 255 0 1]</literal>.
110                     </listitem>
111                 </itemizedlist>
112             </para>
113             <para>-%inf is always converted into the lower bound of the interval (see below).</para>
114             <para>%inf is always converted into the upper bound of the interval (see below).</para>
115             <para>%nan is always converted into 0.</para>
116             <para>If <varname>X</varname> is complex encoded, imaginary parts are ignored.
117                 Only the real parts are converted and returned.
118             </para>
119             <para>[%f %t] is always converted into [0 1].</para>
120             <para>
121             Converting big int64 or uint64 integers into decimal numbers may change them
122             and downgrade their relative accuracy. Indeed, int64|uint64 integers are encoded over
123             63|64 bits, while the mantissa of decimal numbers is encoded over 53 bits only.
124             For more details, please refer to the <link linkend="double">double()</link> page.
125             </para>
126         </warning>
127         <warning>
128             Converting <literal>[]</literal> always keeps it as is, of type 1 (decimal type).
129         </warning>
130         <para>
131             <table>
132                 <tr><th>Function</th><th>y in</th><th align="left">=</th></tr>
133                 <tr><th>int8(X)</th>
134                     <td>[- 2<superscript>7</superscript>,  2<superscript>7</superscript>-1]</td>
135                     <td>[-128, 127]</td>
136                 </tr>
137                 <tr><th>int16(X)</th>
138                     <td>[- 2<superscript>15</superscript>,  2<superscript>15</superscript>-1]</td>
139                     <td>[-32768, 32767]</td>
140                 </tr>
141                 <tr><th>int32(X)</th>
142                     <td>[- 2<superscript>31</superscript>,  2<superscript>31</superscript>-1]</td>
143                     <td>[-2147483648, 2147483647]</td>
144                 </tr>
145                 <tr><th>int64(X)</th>
146                     <td>[- 2<superscript>63</superscript>,  2<superscript>63</superscript>-1]</td>
147                     <td>[-9223372036854775808, 9223372036854775807]</td>
148                 </tr>
149                 <tr><th>uint8(X)</th>
150                     <td>[0, 2<superscript>8</superscript>-1]</td>
151                     <td>[0, 255]</td>
152                 </tr>
153                 <tr><th>uint16(X)</th>
154                     <td>[0, 2<superscript>16</superscript>-1]</td>
155                     <td>[0, 65535]</td>
156                 </tr>
157                 <tr><th>uint32(X)</th>
158                     <td>[0, 2<superscript>32</superscript>-1]</td>
159                     <td>[0, 4294967295]</td>
160                 </tr>
161                 <tr><th>uint64(X)</th>
162                     <td>[0, 2<superscript>64</superscript>-1]</td>
163                     <td>[0, 18446744073709551615]</td>
164                 </tr>
165             </table>
166         </para>
167     </refsection>
168     <refsection role="examples">
169         <title>Examples</title>
170         <para>
171             Rounding to 0 and wrapping, and special values:
172         </para>
173         <programlisting role="example"><![CDATA[
174 int8([-11.7 -8.5 -6.4  6.4 8.5 11.7])
175 int8([-130 -129 -128 -127 126 127 128 129])
176 a = -129 + 256*(-3:3)
177 int8(a)
178 int8([-%inf %inf %nan])
179  ]]></programlisting>
180     <screen><![CDATA[
181 --> int8([-11.7 -8.5 -6.4  6.4 8.5 11.7])
182  ans  =
183  -11 -8 -6  6  8  11
184
185 --> int8([-130 -129 -128 -127 126 127 128 129])
186  ans  =
187   126  127 -128 -127  126  127 -128 -127
188
189 --> a = -129 + 256*(-3:3)
190  a  =
191   -897.  -641.  -385.  -129.   127.   383.   639.
192
193 --> int8(a)
194  ans  =
195   127  127  127  127  127  127  127
196
197 --> int8([-%inf %inf %nan])
198  ans  =
199  -128  127  0
200 ]]></screen>
201     <para>
202         About wrapping and upper bounds of unsigned integers:
203     </para>
204     <programlisting role="example"><![CDATA[
205 uint8([-1 %inf])
206 uint16([-1 %inf])
207 uint32([-1 %inf])
208 uint64([-1 %inf])
209  ]]></programlisting>
210     <screen><![CDATA[
211 --> uint8([-1 %inf])
212  ans  =
213   255  255
214
215 --> uint16([-1 %inf])
216  ans  =
217   65535  65535
218
219 --> uint32([-1 %inf])
220  ans  =
221   4294967295  4294967295
222
223 --> uint64([-1 %inf])
224  ans  =
225   18446744073709551615  18446744073709551615
226 ]]></screen>
227     <para>
228         Converting 64-bits integers into decimal numbers downgrades their accuracy:
229     </para>
230         <programlisting role="example"><![CDATA[
231 i = uint64(2)^63 - 600
232 i - uint64(double(i))
233  ]]></programlisting>
234     <screen><![CDATA[
235 --> i = uint64(2)^63 - 600
236  i  =
237   9223372036854775208
238
239 --> i - uint64(double(i))
240  ans  =
241   424
242 ]]></screen>
243     <para>
244         Converting booleans and complex numbers:
245     </para>
246     <programlisting role="example"><![CDATA[
247 int8([%f %t])
248
249 int8(-10.2 + 3.4*%i)
250 uint8(-10.2 + 3.4*%i)
251  ]]></programlisting>
252     <screen><![CDATA[
253 --> int8([%f %t])
254  ans  =
255   0  1
256
257 --> int8(-10.2 + 3.4*%i)
258  ans  =
259  -10
260
261 --> uint8(-10.2 + 3.4*%i)
262  ans  =
263   246
264 ]]></screen>
265     <para>
266         [] is not convertible:
267     </para>
268     <programlisting role="example"><![CDATA[
269 i = uint16(3);
270 i(1,2) = 5.6
271 typeof(i)
272
273 i = uint16([])
274 i(1,2) = 2.3
275 typeof(i)
276  ]]></programlisting>
277     <screen><![CDATA[
278 --> i = uint16(3);
279 --> i(1,2) = 5.6
280  i  =
281   3  5
282
283 --> typeof(i)
284  ans  =
285  uint16
286
287
288 --> i = uint16([])
289  i  =
290     []
291
292 --> i(1,2) = 2.3
293  i  =
294    0.   2.3
295
296 --> typeof(i)
297  ans  =
298  constant
299 ]]></screen>
300     </refsection>
301     <refsection role="see also">
302         <title>See also</title>
303         <simplelist type="inline">
304             <member>
305                 <link linkend="iconvert">iconvert</link>
306             </member>
307             <member>
308                 <link linkend="inttype">inttype</link>
309             </member>
310             <member>
311                 <link linkend="double">double</link>
312             </member>
313             <member>
314                 <link linkend="dec2bin">dec2bin</link>
315             </member>
316             <member>
317                 <link linkend="dec2base">dec2base</link>
318             </member>
319         </simplelist>
320     </refsection>
321     <refsection role="history">
322         <title>History</title>
323         <revhistory>
324             <revision>
325                 <revnumber>6.0</revnumber>
326                 <revdescription>
327                     <itemizedlist>
328                         <listitem>
329                             int64() and uint64() added to Scilab.
330                         </listitem>
331                         <listitem>
332                             Complex input numbers are now accepted.
333                         </listitem>
334                         <listitem>
335                             <table>
336                                 <tr><th>This</th>               <th>is now</th>     <th>instead of</th></tr>
337                                 <tr><td>int8([-%inf, %inf])</td><td>[-128, 127]</td><td>[0, 0]</td></tr>
338                                 <tr><td>int16([-%inf, %inf])</td><td>[-32768, 32767]</td><td>[0, 0]</td></tr>
339                                 <tr><td>int32(%inf)</td>        <td>2147483647</td> <td>-2147483648</td></tr>
340                                 <tr><td>uint8(%inf)</td>        <td>255</td>        <td>0</td></tr>
341                                 <tr><td>uint16(%inf)</td>       <td>65535</td>      <td>0</td></tr>
342                                 <tr><td>uint32(%inf)</td>       <td>4294967295</td> <td>0</td></tr>
343                             </table>
344                         </listitem>
345                     </itemizedlist>
346                 </revdescription>
347             </revision>
348         </revhistory>
349     </refsection>
350 </refentry>