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>