* Bug #14397 fixed - mgeti did not read u-int64 > 2^52
[scilab.git] / scilab / modules / fileio / help / en_US / mget.xml
index 0ea7c2b..2262938 100644 (file)
-<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * ...
- * 
- * This file must be used under the terms of the CeCILL.
- * This source file is licensed as described in the file COPYING, which
- * you should have received as part of this distribution.  The terms
- * are also available at    
- * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2016 - 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.
  *
  -->
-<!DOCTYPE MAN SYSTEM "../../../../modules/helptools/help.dtd">
-<MAN>
-  <LANGUAGE>eng</LANGUAGE>
-  <TITLE>mget</TITLE>
-  <TYPE>Scilab Function</TYPE>
-  <DATE>$LastChangedDate$</DATE>
-  <SHORT_DESCRIPTION name="mget"> reads  byte or word in a given binary format and convert to double</SHORT_DESCRIPTION>
-  <SHORT_DESCRIPTION name="mgeti"> reads  byte or word in a given binary format return an int type</SHORT_DESCRIPTION>
-  <CALLING_SEQUENCE>
-    <CALLING_SEQUENCE_ITEM>x=mget([n,type,fd])  </CALLING_SEQUENCE_ITEM>
-    <CALLING_SEQUENCE_ITEM>x=mgeti([n,type,fd])  </CALLING_SEQUENCE_ITEM>
-  </CALLING_SEQUENCE>
-  <PARAM>
-    <PARAM_INDENT>
-      <PARAM_ITEM>
-        <PARAM_NAME>n</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>:a positive scalar: The number of items to be read.</SP>
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-      <PARAM_ITEM>
-        <PARAM_NAME>fd</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>: scalar. The <VERB>fd</VERB> parameter returned by the function
-           <VERB>mopen</VERB>. -1 stands for last opened file. Default value
-           is -1.</SP> 
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-      <PARAM_ITEM>
-        <PARAM_NAME>type</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>: a string. Give the binary format used to write all the entries of x.</SP>
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-      <PARAM_ITEM>
-        <PARAM_NAME>x</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>: a vector of floating point or integer type numbers</SP>
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-    </PARAM_INDENT>
-  </PARAM>
-  <DESCRIPTION>
-    <P>
-      The <VERB>mget</VERB> function reads data in the input specified by the
-      stream parameter <VERB>fd</VERB> and returns a vector of floating point data.
-      The <VERB>mgeti</VERB> function reads data in the input specified by the
-      stream parameter <VERB>fd</VERB> and returns a vector of integer data.
-    </P>
-    <P>
-      Data is read at the position at which the file pointer is currently
-      pointing and advances the indicator appropriately.
-    </P>
-    <P>
-      The <VERB>type</VERB> parameter is a conversion specifier which may be set to any of the
-      following flag characters (with default value &quot;l&quot;):
-    </P>
-    <P> <BD>WARNING</BD>, when reading binary files under Windows to not forget to open
-      the file with the <VERB>b</VERB> option like
-      <VERB>fd1=mopen(file1,'rb')</VERB> if not the file will be interpreted as
-      text file and the bytes with value <VERB>13</VERB> will be interpreted as
-      newlines and ommitted. </P>
+<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="mget" xml:lang="en">
+    <refnamediv>
+        <refname>mget</refname>
+        <refpurpose>
+            parses numbers in a binary file and returns them as decimals
+        </refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Syntax</title>
+        <synopsis>
+            D = mget(nNumb)
+            D = mget(nNumb, binFormat)
+            D = mget(nNumb, binFormat, fileID)
+        </synopsis>
+    </refsynopsisdiv>
+    <refnamediv xml:id="mgeti">
+        <refname>mgeti</refname>
+        <refpurpose>
+            parses numbers in a binary file and returns them as encoded integers
+        </refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Syntax</title>
+        <synopsis>
+            I = mgeti(nNumb)
+            I = mgeti(nNumb, binFormat)
+            I = mgeti(nNumb, binFormat, fileID)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>fileID</term>
+                <listitem>
+                    <para>
+                        file identifier (single integer) returned by
+                        <function>mopen</function> when opening the file.
+                        By default, the last opened file is considered.
+                    <important>
+                        The file must be priorly opened in
+                        <emphasis role="bold">r</emphasis>ead
+                        <emphasis role="bold">b</emphasis>inary mode with
+                        <code>fileID = mopen(filename,'rb')</code>.
+                    </important>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>nNumb</term>
+                <listitem>
+                    <para>
+                        Single integer > 0: number of numbers to be
+                        parsed and returned. Each number is encoded over one or
+                        several bytes, according to the used <varname>binFormat</varname>.
+                        <note>To read all numbers remaining in the file, use a
+                        value <varname>nNumb</varname> big enough.
+                        </note>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>binFormat</term>
+                <listitem>
+                    <para>
+                        a text word made of one, 2 or 3 character codes: the binary
+                        format used to parse numbers in the binary file.
+                        Available binary codes are the following:
+                    <table>
+                        <tr valign="top">
+                            <td align="right">c</td>
+                            <td>: individual bytes parsed as
+                                <literal>int8</literal> integers
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">uc</td>
+                            <td>: individual bytes parsed as
+                                <literal>uint8</literal> unsigned integers >0
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">s</td>
+                            <td>: 2-byte blocks parsed as
+                                <literal>int16</literal> integers
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">us</td>
+                            <td>: 2-byte blocks parsed as
+                                <literal>uint16</literal> unsigned integers >0
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">i</td>
+                            <td>: 4-byte blocks parsed as
+                                <literal>int32</literal> integers
+                                (<emphasis role="bold">default mode</emphasis>).
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">ui</td>
+                            <td>: 4-byte blocks parsed as
+                                <literal>uint32</literal> unsigned integers >0
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">l</td>
+                            <td>: 8-byte blocks parsed as
+                                <literal>int64</literal> integers
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">ul</td>
+                            <td>: 8-byte blocks parsed as
+                                <literal>uint64</literal> unsigned integers >0
+                            </td>
+                        </tr>
+                        <tr>
+                            <td/>
+                            <td>
+                                Only with <function>mget()</function> :
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">f</td>
+                            <td>: 4-byte blocks parsed as
+                                "single precision" decimal numbers
+                                (so-called "<emphasis role="bold">f</emphasis>loats"
+                                in oldies)
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">d</td>
+                            <td>: 8-byte blocks parsed as
+                                <emphasis role="bold">d</emphasis>ecimal numbers
+                            </td>
+                        </tr>
+                    </table>
+                    </para>
+                    <para>
+                        The default order of bytes in a block can be set using
+                        a <function>mopen</function> option when opening the file.
+                        This order may be forced afterwards using an optional
+                        <function>mget</function> or <function>mgeti</function>
+                        flag to be appended to <varname>binFormat</varname>:
+                        <table>
+                            <tr valign="top">
+                                <td align="right">..l :</td>
+                                <td><emphasis role="bold">l</emphasis>ittle endian
+                                (first byte in the block = low power byte)
+                                </td>
+                            </tr>
+                            <tr valign="top">
+                                <td align="right">..b :</td>
+                                <td><emphasis role="bold">b</emphasis>ig endian
+                                (first byte in the block = high power byte)
+                                </td>
+                            </tr>
+                        </table>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>D</term>
+                <listitem>
+                    <para>
+                        Row of <varname>nNumb</varname> Decimal numbers
+                        (or available ones if the End Of File has been reached).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>I</term>
+                <listitem>
+                    <para>
+                        Row of <varname>nNumb</varname> encoded Integers
+                        (or available ones if the End Of File has been reached).
+                        The <function>inttype</function> of returned integers
+                        depends on the used <varname>binFormat</varname>.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            <function>mget</function> and <function>mgeti</function> start reading
+            bytes in the specified file from the current position of the inner
+            file pointer. After reading a block of N bytes (N==1,2,4,8 according
+            to the chosen <varname>binFormat</varname>),
+            <itemizedlist>
+                <listitem>
+                    the file pointer is increased by N bytes and set to the
+                    beginning of next block.
+                </listitem>
+                <listitem>
+                    the read block is ordered according to the default or chosen
+                    swapping endian mode. The parsed block is then stored to
+                    be returned.
+                </listitem>
+            </itemizedlist>
+            This is iterated <varname>nNumb</varname> times, unless
+            the End Of File is reached: In this case, parsing the file is
+            stopped, the uncomplete block is left (if any), the EOF status is set,
+            and already parsed numbers are returned.
+        </para>
+        <para>
+            When <function>mgeti()</function> is used, parsed numbers are
+            converted into the <function>inttype</function> corresponding to
+            the chosen <varname>binFormat</varname> and then returned.
+        </para>
+        <para>
+            When <function>mget()</function> is used, binary numbers are
+            parsed according to <varname>binFormat</varname> but are finally
+            converted into 8-byte decimal numbers and then returned.
+            <warning>
+            If <literal>int64</literal> or <literal>uint64</literal>
+            integers > 2<superscript>53</superscript> were parsed thanks
+            to the <literal>"ul*"</literal> or <literal>"l*"</literal> format,
+            their final conversion into decimal numbers
+            truncates their mantissa to their 53 highest bits.
+            </warning>
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+binfile = TMPDIR+"/mgetest.bin";
+idF = mopen(binfile, "w+b");
+mput(int8(0:16),"uc");
+
+ mseek(0);
+ mgeti(1,"uc")  // 0 expected
+ mgeti(2,"uc")  // 1, 2 expected
+[mgeti(1,"us"),  uint16(3 + 4*256)]
+ mseek(3);      // back to the previous position on "3"
+[mgeti(1,"usb"), uint16(4 + 3*256)] // swapped bytes (big endian)
+ mseek(0);
+[mgeti(1,"ui") , uint32(0 + 256*(1 + 256*(2 + 256*3)))]
+ mseek(0);
+[mgeti(1,"uib"), uint32(3 + 256*(2 + 256*(1 + 256*0)))]
+mclose(idF);
+
+// uint64 and int64 integers with a relative accuracy of 1/2^64 = %eps/2^12
+// better than decimals one are well handled:
+    // Generating n 64-bit long integers with bits #0-#63 set randomly:
+n = 5;
+b = grand(64,n,"uin",0,1);
+p = uint64(2).^ndgrid(0:63,1:n);
+x0 = sum(b.*p, "r");
+
+    // We write them in a file, and then re-read them with mgeti():
+for usign = ["u" ""]
+    for endian = ["l" "b"]
+        binfile = TMPDIR+"/mgetiTestInt64.dat";
+        idF = mopen(binfile, "w+b");
+        x = x0;
+        if usign==""
+            x = int64(x);
+        end
+        mput(x,usign+"l"+endian)   // "l" is mandatory to manage all the 64 bits
 
-    <DESCRIPTION_INDENT>
-      <DESCRIPTION_ITEM label="&quot;l&quot;, &quot;i&quot;, &quot;s&quot;, &quot;ul&quot;,
-       &quot;ui&quot;, &quot;us&quot;, &quot;d&quot;, &quot;f&quot;,
-       &quot;c&quot;, &quot;uc&quot;"> 
-        <SP>: for reading respectively a long, an int, a short, an unsigned
-         long, an unsigned int, an unsigned short, a double, a float, a char
-         and an unsigned char. The bytes which are read are automatically
-         swapped if necessary (by checking little-endian status). This default
-         swapping mode can be suppressed by adding a flag in the
-         <VERB>mopen</VERB> function. Format &quot;l&quot;, &quot;d&quot; and
-         &quot;f&quot; are valid only with the <VERB>mget</VERB>
-         function.</SP> 
-      </DESCRIPTION_ITEM>
-      <DESCRIPTION_ITEM label="&quot;..l&quot; or &quot;..b&quot;">
-        <SP>: It is also possible to read in little-endian or big-endian mode
-         by adding a 'l' or 'b' character at the end of a type
-         specification. For example &quot;db&quot; will read a double in
-         big-endian mode.</SP> 
-      </DESCRIPTION_ITEM>
-    </DESCRIPTION_INDENT>
-  </DESCRIPTION>
-  <EXAMPLE>
-    <![CDATA[
-    file1 = 'test1.bin';
-    file2 = 'test2.bin';
-    fd1=mopen(file1,'wb');
-    fd2=mopen(file2,'wb');
-    mput(1996,'ull',fd1);
-    mput(1996,'ull',fd2);
-    mclose(fd1);
-    mclose(fd2);
+        // Now, read them in the same mode:
+        mseek(0);
+        xr = mgeti(n, usign+"l"+endian);
+        mclose(idF);
 
-    fd1=mopen(file1,'rb');
-    if 1996<>mget(1,'ull',fd1) ;write(%io(2),'Bug');end;
-    fd2=mopen(file2,'rb');
-    if 1996<>mget(1,'ull',fd2) ;write(%io(2),'Bug');end;
-    mclose(fd1);
-    mclose(fd2);
-    ]]>
-  </EXAMPLE>
-  <SEE_ALSO>
-    <SEE_ALSO_ITEM>
-      <LINK>mclose</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>meof</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mfprintf</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>fprintfMat</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mfscanf</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>fscanfMat</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mgetl</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mgetstr</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mopen</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mprintf</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mput</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mputl</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mputstr</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mscanf</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mseek</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mtell</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>mdelete</LINK>
-    </SEE_ALSO_ITEM>
-  </SEE_ALSO>
-</MAN>
+        // Display:
+        wrParse = usign + "l" + endian;
+        printf("    Write as  ""%s""       Read as ""%s""\n", wrParse, wrParse);
+        [x' xr']
+    end
+end
+ ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="mopen">mopen</link>
+            </member>
+            <member>
+                <link linkend="mclose">mclose</link>
+            </member>
+            <member>
+                <link linkend="mput">mput</link>
+            </member>
+            <member>
+                <link linkend="mseek">mseek</link>
+            </member>
+            <member>
+                <link linkend="mtell">mtell</link>
+            </member>
+            <member>
+                <link linkend="meof">meof</link>
+            </member>
+            <member>
+                <link linkend="readb">readb</link>
+            </member>
+            <member>
+                <link linkend="read4b">read4b</link>
+            </member>
+            <member>
+                <link linkend="inttype">inttype</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>mgeti(,"ul*"|"l*") is implemented
+                 to read uint64 or int64 integers > 2<superscript>52</superscript>.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>