* Bug #14397 fixed - mgeti did not read u-int64 > 2^52
[scilab.git] / scilab / modules / fileio / help / en_US / mget.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  * ...
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2016 - Samuel GOUGEON
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:ns5="http://www.w3.org/1999/xhtml"
19     xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20     xmlns:scilab="http://www.scilab.org" xml:id="mget" xml:lang="en">
21     <refnamediv>
22         <refname>mget</refname>
23         <refpurpose>
24             parses numbers in a binary file and returns them as decimals
25         </refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Syntax</title>
29         <synopsis>
30             D = mget(nNumb)
31             D = mget(nNumb, binFormat)
32             D = mget(nNumb, binFormat, fileID)
33         </synopsis>
34     </refsynopsisdiv>
35     <refnamediv xml:id="mgeti">
36         <refname>mgeti</refname>
37         <refpurpose>
38             parses numbers in a binary file and returns them as encoded integers
39         </refpurpose>
40     </refnamediv>
41     <refsynopsisdiv>
42         <title>Syntax</title>
43         <synopsis>
44             I = mgeti(nNumb)
45             I = mgeti(nNumb, binFormat)
46             I = mgeti(nNumb, binFormat, fileID)
47         </synopsis>
48     </refsynopsisdiv>
49     <refsection>
50         <title>Arguments</title>
51         <variablelist>
52             <varlistentry>
53                 <term>fileID</term>
54                 <listitem>
55                     <para>
56                         file identifier (single integer) returned by
57                         <function>mopen</function> when opening the file.
58                         By default, the last opened file is considered.
59                     <important>
60                         The file must be priorly opened in
61                         <emphasis role="bold">r</emphasis>ead
62                         <emphasis role="bold">b</emphasis>inary mode with
63                         <code>fileID = mopen(filename,'rb')</code>.
64                     </important>
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>nNumb</term>
70                 <listitem>
71                     <para>
72                         Single integer > 0: number of numbers to be
73                         parsed and returned. Each number is encoded over one or
74                         several bytes, according to the used <varname>binFormat</varname>.
75                         <note>To read all numbers remaining in the file, use a
76                         value <varname>nNumb</varname> big enough.
77                         </note>
78                     </para>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>binFormat</term>
83                 <listitem>
84                     <para>
85                         a text word made of one, 2 or 3 character codes: the binary
86                         format used to parse numbers in the binary file.
87                         Available binary codes are the following:
88                     <table>
89                         <tr valign="top">
90                             <td align="right">c</td>
91                             <td>: individual bytes parsed as
92                                 <literal>int8</literal> integers
93                             </td>
94                         </tr>
95                         <tr valign="top">
96                             <td align="right">uc</td>
97                             <td>: individual bytes parsed as
98                                 <literal>uint8</literal> unsigned integers >0
99                             </td>
100                         </tr>
101                         <tr valign="top">
102                             <td align="right">s</td>
103                             <td>: 2-byte blocks parsed as
104                                 <literal>int16</literal> integers
105                             </td>
106                         </tr>
107                         <tr valign="top">
108                             <td align="right">us</td>
109                             <td>: 2-byte blocks parsed as
110                                 <literal>uint16</literal> unsigned integers >0
111                             </td>
112                         </tr>
113                         <tr valign="top">
114                             <td align="right">i</td>
115                             <td>: 4-byte blocks parsed as
116                                 <literal>int32</literal> integers
117                                 (<emphasis role="bold">default mode</emphasis>).
118                             </td>
119                         </tr>
120                         <tr valign="top">
121                             <td align="right">ui</td>
122                             <td>: 4-byte blocks parsed as
123                                 <literal>uint32</literal> unsigned integers >0
124                             </td>
125                         </tr>
126                         <tr valign="top">
127                             <td align="right">l</td>
128                             <td>: 8-byte blocks parsed as
129                                 <literal>int64</literal> integers
130                             </td>
131                         </tr>
132                         <tr valign="top">
133                             <td align="right">ul</td>
134                             <td>: 8-byte blocks parsed as
135                                 <literal>uint64</literal> unsigned integers >0
136                             </td>
137                         </tr>
138                         <tr>
139                             <td/>
140                             <td>
141                                 Only with <function>mget()</function> :
142                             </td>
143                         </tr>
144                         <tr valign="top">
145                             <td align="right">f</td>
146                             <td>: 4-byte blocks parsed as
147                                 "single precision" decimal numbers
148                                 (so-called "<emphasis role="bold">f</emphasis>loats"
149                                 in oldies)
150                             </td>
151                         </tr>
152                         <tr valign="top">
153                             <td align="right">d</td>
154                             <td>: 8-byte blocks parsed as
155                                 <emphasis role="bold">d</emphasis>ecimal numbers
156                             </td>
157                         </tr>
158                     </table>
159                     </para>
160                     <para>
161                         The default order of bytes in a block can be set using
162                         a <function>mopen</function> option when opening the file.
163                         This order may be forced afterwards using an optional
164                         <function>mget</function> or <function>mgeti</function>
165                         flag to be appended to <varname>binFormat</varname>:
166                         <table>
167                             <tr valign="top">
168                                 <td align="right">..l :</td>
169                                 <td><emphasis role="bold">l</emphasis>ittle endian
170                                 (first byte in the block = low power byte)
171                                 </td>
172                             </tr>
173                             <tr valign="top">
174                                 <td align="right">..b :</td>
175                                 <td><emphasis role="bold">b</emphasis>ig endian
176                                 (first byte in the block = high power byte)
177                                 </td>
178                             </tr>
179                         </table>
180                     </para>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>D</term>
185                 <listitem>
186                     <para>
187                         Row of <varname>nNumb</varname> Decimal numbers
188                         (or available ones if the End Of File has been reached).
189                     </para>
190                 </listitem>
191             </varlistentry>
192             <varlistentry>
193                 <term>I</term>
194                 <listitem>
195                     <para>
196                         Row of <varname>nNumb</varname> encoded Integers
197                         (or available ones if the End Of File has been reached).
198                         The <function>inttype</function> of returned integers
199                         depends on the used <varname>binFormat</varname>.
200                     </para>
201                 </listitem>
202             </varlistentry>
203         </variablelist>
204     </refsection>
205     <refsection>
206         <title>Description</title>
207         <para>
208             <function>mget</function> and <function>mgeti</function> start reading
209             bytes in the specified file from the current position of the inner
210             file pointer. After reading a block of N bytes (N==1,2,4,8 according
211             to the chosen <varname>binFormat</varname>),
212             <itemizedlist>
213                 <listitem>
214                     the file pointer is increased by N bytes and set to the
215                     beginning of next block.
216                 </listitem>
217                 <listitem>
218                     the read block is ordered according to the default or chosen
219                     swapping endian mode. The parsed block is then stored to
220                     be returned.
221                 </listitem>
222             </itemizedlist>
223             This is iterated <varname>nNumb</varname> times, unless
224             the End Of File is reached: In this case, parsing the file is
225             stopped, the uncomplete block is left (if any), the EOF status is set,
226             and already parsed numbers are returned.
227         </para>
228         <para>
229             When <function>mgeti()</function> is used, parsed numbers are
230             converted into the <function>inttype</function> corresponding to
231             the chosen <varname>binFormat</varname> and then returned.
232         </para>
233         <para>
234             When <function>mget()</function> is used, binary numbers are
235             parsed according to <varname>binFormat</varname> but are finally
236             converted into 8-byte decimal numbers and then returned.
237             <warning>
238             If <literal>int64</literal> or <literal>uint64</literal>
239             integers > 2<superscript>53</superscript> were parsed thanks
240             to the <literal>"ul*"</literal> or <literal>"l*"</literal> format,
241             their final conversion into decimal numbers
242             truncates their mantissa to their 53 highest bits.
243             </warning>
244         </para>
245     </refsection>
246     <refsection>
247         <title>Examples</title>
248         <programlisting role="example"><![CDATA[
249 binfile = TMPDIR+"/mgetest.bin";
250 idF = mopen(binfile, "w+b");
251 mput(int8(0:16),"uc");
252
253  mseek(0);
254  mgeti(1,"uc")  // 0 expected
255  mgeti(2,"uc")  // 1, 2 expected
256 [mgeti(1,"us"),  uint16(3 + 4*256)]
257  mseek(3);      // back to the previous position on "3"
258 [mgeti(1,"usb"), uint16(4 + 3*256)] // swapped bytes (big endian)
259  mseek(0);
260 [mgeti(1,"ui") , uint32(0 + 256*(1 + 256*(2 + 256*3)))]
261  mseek(0);
262 [mgeti(1,"uib"), uint32(3 + 256*(2 + 256*(1 + 256*0)))]
263 mclose(idF);
264
265 // uint64 and int64 integers with a relative accuracy of 1/2^64 = %eps/2^12
266 // better than decimals one are well handled:
267     // Generating n 64-bit long integers with bits #0-#63 set randomly:
268 n = 5;
269 b = grand(64,n,"uin",0,1);
270 p = uint64(2).^ndgrid(0:63,1:n);
271 x0 = sum(b.*p, "r");
272
273     // We write them in a file, and then re-read them with mgeti():
274 for usign = ["u" ""]
275     for endian = ["l" "b"]
276         binfile = TMPDIR+"/mgetiTestInt64.dat";
277         idF = mopen(binfile, "w+b");
278         x = x0;
279         if usign==""
280             x = int64(x);
281         end
282         mput(x,usign+"l"+endian)   // "l" is mandatory to manage all the 64 bits
283
284         // Now, read them in the same mode:
285         mseek(0);
286         xr = mgeti(n, usign+"l"+endian);
287         mclose(idF);
288
289         // Display:
290         wrParse = usign + "l" + endian;
291         printf("    Write as  ""%s""       Read as ""%s""\n", wrParse, wrParse);
292         [x' xr']
293     end
294 end
295  ]]></programlisting>
296     </refsection>
297     <refsection role="see also">
298         <title>See also</title>
299         <simplelist type="inline">
300             <member>
301                 <link linkend="mopen">mopen</link>
302             </member>
303             <member>
304                 <link linkend="mclose">mclose</link>
305             </member>
306             <member>
307                 <link linkend="mput">mput</link>
308             </member>
309             <member>
310                 <link linkend="mseek">mseek</link>
311             </member>
312             <member>
313                 <link linkend="mtell">mtell</link>
314             </member>
315             <member>
316                 <link linkend="meof">meof</link>
317             </member>
318             <member>
319                 <link linkend="readb">readb</link>
320             </member>
321             <member>
322                 <link linkend="read4b">read4b</link>
323             </member>
324             <member>
325                 <link linkend="inttype">inttype</link>
326             </member>
327         </simplelist>
328     </refsection>
329     <refsection role="history">
330         <title>History</title>
331         <revhistory>
332             <revision>
333                 <revnumber>6.1.0</revnumber>
334                 <revdescription>mgeti(,"ul*"|"l*") is implemented
335                  to read uint64 or int64 integers > 2<superscript>52</superscript>.
336                 </revdescription>
337             </revision>
338         </revhistory>
339     </refsection>
340 </refentry>