* Bug #14390 fixed - double() help page had irrelevant syntaxes and was poor
[scilab.git] / scilab / modules / elementary_functions / help / en_US / floating_point / double.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) 2016 - Samuel GOUGEON
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="double" xml:lang="en">
17     <refnamediv>
18         <refname>double</refname>
19         <refpurpose>converts inttype integers or booleans into decimal encoding
20         </refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>y = double(X)
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection role="parameters">
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>X</term>
32                 <listitem>
33                     <para>matrix of encoded integers or booleans</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>y</term>
38                 <listitem>
39                     <para>matrix of numbers in decimal notation</para>
40                 </listitem>
41             </varlistentry>
42         </variablelist>
43     </refsection>
44     <refsection role="description">
45         <title>Description</title>
46         <para>converts data stored using 1, 2, 4 or 8 bytes integers into
47             decimal representation on 8 bytes. If <literal>X</literal>
48                 entries are already double precision floats, nothing is done.
49           <note><function>double()</function> and <literal>iconvert(..,0)</literal>
50           are equivalent and have the same speed.
51           </note>
52           <note>Booleans can also be processed with <function>double()</function>.
53             However, <literal>bool2s()</literal> does it roughly twice faster.
54           </note>
55           <important>Since the mantissa of <literal>uint64</literal> is encoded on
56           64 bits while the mantissa of (<literal>double</literal> precision) decimal
57           numbers is encoded only on 52 bits, the relative accuracy of
58           <literal>uint64</literal> integers greater than 2<superscript>52</superscript>
59           may then be up to
60           2<superscript>12</superscript> ~4000 times better for them
61           than for "<literal>double</literal>". As a consequence, applying
62           <function>double()</function> on <literal>int64</literal> or
63           <literal>uint64</literal> integers greater than 2<superscript>52</superscript>
64           change their values
65           and downgrades their accuracy (roundoff errors). Some examples illustrating
66           such effects are provided herebelow.
67           </important>
68         </para>
69     </refsection>
70
71     <refsection role="examples">
72         <title>Examples</title>
73         <programlisting role="example"><![CDATA[
74 x = int8([0 12 140])
75 double(x)
76
77 // Applying double() rounds off and truncates int64() or uint64() numbers
78 // ----------------------------------------------------------------------
79 i = int64(2)^52        // 52 bits, as for decimal numbers mantissa
80 i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
81 err = i - double(i)    // no errors for |integers|<= 2^52
82 i = int64(2)^53        // 53 bits integers => more accurate than decimal numbers
83 i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
84 err = i - double(i)    // round-off errors appear
85 i = int64(2)^55
86 i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
87 err = i - double(i)
88 i = int64(2)^62
89 i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
90 err = i - double(i)
91 ]]></programlisting>
92     <screen>
93 <![CDATA[--> i = int64(2)^52     // 52 bits, as for decimal numbers mantissa
94  i  =
95   4503599627370496
96
97 --> i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
98  i  =
99   4503599627370496  4503599627370499  4503599627370526
100   4503599627370499  4503599627370529  4503599627370826
101   4503599627370502  4503599627370559  4503599627371126
102   4503599627370505  4503599627370589  4503599627371426
103
104 --> err = i - double(i)   // no errors for |integers|<= 2^52
105  err  =
106   0  0  0
107   0  0  0
108   0  0  0
109   0  0  0
110
111 --> i = int64(2)^53      // 53 bits integers => more accurate than decimal numbers
112  i  =
113   9007199254740992
114
115 --> i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
116  i  =
117   9007199254740992  9007199254740995  9007199254741022
118   9007199254740995  9007199254741025  9007199254741322
119   9007199254740998  9007199254741055  9007199254741622
120   9007199254741001  9007199254741085  9007199254741922
121
122 --> err = i - double(i)     // round-off errors appear
123  err  =
124   0 -1  0
125  -1  1  0
126   0 -1  0
127   1  1  0
128
129 --> i = int64(2)^55
130  i  =
131   36028797018963968
132
133 --> i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
134  i  =
135   36028797018963968  36028797018963971  36028797018963998
136   36028797018963971  36028797018964001  36028797018964298
137   36028797018963974  36028797018964031  36028797018964598
138   36028797018963977  36028797018964061  36028797018964898
139
140 --> err = i - double(i)
141  err  =
142   0  3 -2
143   3  1  2
144  -2 -1 -2
145   1 -3  2
146
147 --> i = int64(2)^62
148  i  =
149   4611686018427387904
150
151 --> i = [i+(0:3:9)'  i+(3:30:93)'  i+(30:300:930)']
152  i  =
153   4611686018427387904  4611686018427387907  4611686018427387934
154   4611686018427387907  4611686018427387937  4611686018427388234
155   4611686018427387910  4611686018427387967  4611686018427388534
156   4611686018427387913  4611686018427387997  4611686018427388834
157
158 --> err = i - double(i)
159  err  =
160   0  3  30
161   3  33  330
162   6  63 -394
163   9  93 -94
164 ]]></screen>
165         <para></para>
166         <programlisting role="example"><![CDATA[
167 // Comparing speeds of double(), bool2s() and iconvert(,0) on booleans
168 // -------------------------------------------------------------------
169 b = (rand(1000,1000)<0.5);
170 tic(),for i=1:100, bool2s(b); end, toc()
171 tic(),for i=1:100, double(b); end, toc()
172 tic(),for i=1:100, iconvert(b,0); end, toc()
173  ]]></programlisting>
174     <screen>
175 <![CDATA[--> b = (rand(1000,1000)<0.5);
176 --> tic(),for i=1:100, bool2s(b); end, toc()
177  ans  =
178    1.1680533
179
180 --> tic(),for i=1:100, double(b); end, toc()
181  ans  =
182    2.9003021
183
184 --> tic(),for i=1:100, iconvert(b,0); end, toc()
185  ans  =
186    2.1867567
187 ]]></screen>
188         <para></para>
189       <programlisting role="example"><![CDATA[
190 // Speed comparison between double() and iconvert(..,0) on int32 integers
191 // ----------------------------------------------------------------------
192 i = int32((rand(1000,1000)-0.5)*1000);
193 tic(),for j=1:100, double(i); end, toc()
194 tic(),for j=1:100, iconvert(i,0); end, toc()
195  ]]></programlisting>
196       <screen>
197 <![CDATA[--> i = int32((rand(1000,1000)-0.5)*10000);
198 --> tic(),for j=1:100, double(i); end, toc()
199  ans  =
200    2.2464656
201
202 --> tic(),for j=1:100, iconvert(i,0); end, toc()
203  ans  =
204    2.2771408
205 ]]></screen>
206     </refsection>
207
208     <refsection role="see also">
209         <title>See Also</title>
210         <simplelist type="inline">
211             <member>
212                 <link linkend="iconvert">iconvert</link>
213             </member>
214             <member>
215                 <link linkend="bool2s">bool2s</link>
216             </member>
217             <member>
218                 <link linkend="int8">int8</link>
219             </member>
220             <member>
221                 <link linkend="inttype">inttype</link>
222             </member>
223             <member>
224                 <link linkend="type">type</link>
225             </member>
226             <member>
227                 <link linkend="bin2dec">bin2dec</link>
228             </member>
229             <member>
230                 <link linkend="oct2dec">oct2dec</link>
231             </member>
232             <member>
233                 <link linkend="hex2dec">hex2dec</link>
234             </member>
235             <member>
236                 <link linkend="base2dec">base2dec</link>
237             </member>
238         </simplelist>
239     </refsection>
240       <refsection role="history">
241         <title>History</title>
242         <revhistory>
243             <revision>
244                 <revnumber>6.0</revnumber>
245                 <revdescription>
246                     New int64 and uint64 encoded integers can now be converted.
247                 </revdescription>
248             </revision>
249         </revhistory>
250     </refsection>
251 </refentry>