* Bug #14397 fixed - mgeti did not read u-int64 > 2^52
[scilab.git] / scilab / modules / fileio / help / ru_RU / mget.xml
index 58e3e4a..55069f2 100644 (file)
@@ -2,9 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
- * ...
- *
  * 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.
  * along with this program.
  *
  -->
-<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="ru">
+<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="ru">
     <refnamediv>
         <refname>mget</refname>
         <refpurpose>
-            считывает байт или слово в заданном двоичном формате и преобразует в
-            число удвоенной точности
+            проверяет числа в двоичом файле и возвращает их в виде десятичных чисел
         </refpurpose>
     </refnamediv>
+    <refsynopsisdiv>
+        <title>Синтаксис</title>
+        <synopsis>
+            D = mget(nNumb)
+            D = mget(nNumb, binFormat)
+            D = mget(nNumb, binFormat, fileID)
+        </synopsis>
+    </refsynopsisdiv>
     <refnamediv xml:id="mgeti">
         <refname>mgeti</refname>
         <refpurpose>
-            считывает байт или слово в заданном двоичном формате и возвращает
-            целочисленное значение типа int
+            проверяет числа в двоичом файле и возвращает их в виде кодированных целых чисел
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
         <synopsis>
-            x = mget([n, type, fd])
-            x = mgeti([n, type, fd])
+            I = mgeti(nNumb)
+            I = mgeti(nNumb, binFormat)
+            I = mgeti(nNumb, binFormat, fileID)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>n</term>
-                <listitem>
-                    <para>положительный скаляр: количество считываемых данных.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>fd</term>
+                <term>fileID</term>
                 <listitem>
                     <para>
-                        скаляр: параметр <varname>fd</varname>, возращённый функцией <function>mopen</function>. Для последнего открытого файла ставится -1. Значение по умолчанию -1.
+                        идентификатор файла (целое число типа single), возвращаемое
+                        функцией <function>mopen</function> при открытии файла.
+                        По умолчанию используется последний открытый файл.
+                    <important>
+                        Файл должен быть открыт в режиме чтения двоичных данных
+                        с помощью инструкции <code>fileID = mopen(filename,'rb')</code>.
+                    </important>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>type</term>
+                <term>nNumb</term>
                 <listitem>
                     <para>
-                        строка: двоичный формат, используемый для записи всех элементов
-                        <varname>x</varname>.
+                        Целое положительное число типа single: количество чисел,
+                        которые следует проверить и вернуть. Каждое число
+                        закодировано одним или несколькими байтами, в соответствии
+                        с используемым форматом <varname>binFormat</varname>.
+                        <note>
+                        Чтобы прочитать все числа, оставшиеся в файле, используйте
+                        достаточно большое значение <varname>nNumb</varname>.
+                        </note>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x</term>
+                <term>binFormat</term>
                 <listitem>
                     <para>
-                        вектор целых чисел или чисел с плавающей запятой.
+                        текстовое значение составленное из одного, двух или трёх
+                        символов-кодов: двоичный формат, используемый для проверки
+                        чисел в двоичном файле. Доступны следующие двоичные коды:
+                    <table>
+                        <tr valign="top">
+                            <td align="right">c</td>
+                            <td>: индивидуальные байты проверяются как целые числа
+                                типа <literal>int8</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">uc</td>
+                            <td>: индивидуальные байты проверяются как целые
+                                беззнаковые положительные числа типа <literal>uint8</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">s</td>
+                            <td>: двухбайтные блоки проверяются как целые числа типа
+                                <literal>int16</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">us</td>
+                            <td>: двухбайтные блоки проверяются как целые беззнаковые
+                                положительные числа типа <literal>uint16</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">i</td>
+                            <td>: четырёхбайтные блоки проверяются как целые числа
+                                типа <literal>int32</literal>
+                                (<emphasis role="bold">режим по умолчанию</emphasis>).
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">ui</td>
+                            <td>: четырёхбайтные блоки проверяются как целые
+                                беззнаковые положительные числа типа <literal>uint32</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">l</td>
+                            <td>: восьми байтные блоки проверяются как целые числа
+                                типа <literal>int64</literal>;
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">ul</td>
+                            <td>: восьмибайтные блоки проверяются как целые
+                                беззнаковые положительные числа типа
+                                <literal>uint64</literal>;
+                            </td>
+                        </tr>
+                        <tr>
+                            <td/>
+                            <td>
+                                Только с <function>mget()</function> :
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">f</td>
+                            <td>: четырёхбайтные блоки проверяются как десятичные
+                                числа "одинарной точности" (так называемые "числа
+                                с плавающей запятой", "<emphasis role="bold">f</emphasis>loats")
+                            </td>
+                        </tr>
+                        <tr valign="top">
+                            <td align="right">d</td>
+                            <td>: восьмибайтные блоки проверяются как десятичные
+                                ("<emphasis role="bold">d</emphasis>ecimal") числа.
+                            </td>
+                        </tr>
+                    </table>
                     </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Описание</title>
-        <para>
-            Функция <function>mget</function> считывает данные со входа, определённого параметром потока <varname>fd</varname> и возвращает вектор данных с плавающей запятой.
-        </para>
-
-        <para>
-            Функция <function>mgeti</function> считывает данные со входа, определённого параметром потока <varname>fd</varname> и возвращает вектор целочисленных данных.
-        </para>
-        <para>
-            Данные считываются в положении, на которое в данный момент указывает указатель файла и передвигает индикатор далее соответствующим образом.
-        </para>
-        <para>
-            Параметр <varname>type</varname> является указателем преобразования, который может быть установлен в любой из следующих символов-флагов (со значением по умолчанию <literal>"l"</literal>):
-        </para>
-        <para>
-            <note>
-                В Windows, поведение по умолчанию состоит в пропуске байта 13 (<literal>0x0D</literal>).
-                Функцию <function>mopen</function> следует вызывать с опцией
-                <literal>'b'</literal>, например, <code>fd1 = mopen(file1,'rb')</code>, так что все байты без исключения будут прочитаны.
-            </note>
-        </para>
-        <para>Тип данных:</para>
-        <variablelist>
-            <varlistentry>
-                <term>d</term>
-                <listitem>
-                    <para>удвоенная точность, double</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>f</term>
-                <listitem>
-                    <para>плавающая запятая, float</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>l</term>
-                <listitem>
-                    <para>длинное, long long</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>i</term>
-                <listitem>
-                    <para>целочисленное, int (long int)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>s</term>
-                <listitem>
-                    <para>короткое, short</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>c</term>
-                <listitem>
-                    <para>символ, character</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <para>Необязательный флаг:</para>
-        <variablelist>
-            <varlistentry>
-                <term>u..</term>
-                <listitem>
                     <para>
-                        беззнаковый (в сочетании с одним из вышеперечисленных типов)
+                        По умолчанию порядок байтов в блоке может быть установлен
+                        с помощью опции функции <function>mopen</function> при
+                        открытии файла. Этот порядок затем может принудительно
+                        быть использован с помощью настроечного флага функции
+                        <function>mget</function> или <function>mgeti</function>,
+                        который добавляется к <varname>binFormat</varname>:
+                        <table>
+                            <tr valign="top">
+                                <td align="right">..l :</td>
+                                <td>прямой порядок байтов (
+                                <emphasis role="bold">l</emphasis>ittle endian
+                                (младший байт идёт в начале блока);
+                                </td>
+                            </tr>
+                            <tr valign="top">
+                                <td align="right">..b :</td>
+                                <td>обратный порядок байтов (
+                                <emphasis role="bold">b</emphasis>ig endian
+                                (старший байт идёт в начале блока).
+                                </td>
+                            </tr>
+                        </table>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>..l</term>
+                <term>D</term>
                 <listitem>
                     <para>
-                        прямой порядок байтов (в сочетании с одним из вышеперечисленных
-                        типов)
+                        Ряд из <varname>nNumb</varname> десятичных чисел
+                        (или имеющихся чисел, если достигнут конец файла).
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>..b</term>
+                <term>I</term>
                 <listitem>
                     <para>
-                        обратный порядок байтов (в сочетании с одним из вышеперечисленных
-                        типов)
+                        Ряд из <varname>nNumb</varname> закодированных целых чисел
+                        (или имеющихся чисел, если достигнут конец файла).
+                        Функция <function>inttype</function> возвращённых целых чисел
+                        зависит от используемого формата <varname>binFormat</varname>.
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
+    </refsection>
+    <refsection>
+        <title>Описание</title>
         <para>
-            Чтение байтов автоматически переключается при необходимости (с помощью проверки статуса <literal>little=endian</literal>).
-        </para>
+            Функции <function>mget</function> и <function>mgeti</function> начинают
+            чтение байтов в указанном файле с текущей позиции внутреннего файлового
+            указателя. После чтения блока из <literal>N</literal> байтов
+            (<literal>N==1,2,4,8</literal> в соответствии с выбранным форматом
+            <varname>binFormat</varname>),
+            <itemizedlist>
+                <listitem>
+                    файловый указатель увеличивается на <literal>N</literal>
+                    байтов и устанавливается в начало следующего блока;
+                </listitem>
+                <listitem>
+                    блоки чтения идут в порядке, соответствующем выбранному или
+                    установленному по умолчанию режиму порядка байтов.
+                    Проверяемый блок затем сохраняется для возврата.
+                </listitem>
+            </itemizedlist>
+            Эти действия повторяются <varname>nNumb</varname> раз до тех пор,
+            пока не будет достигнут конец файла: в этом случае проверка файла
+            прекращается, неполный блок остаётся (если он есть), взводится статус
+            <literal>EOF</literal> и уже проверенные числа возвращаются.
+       </para>
         <para>
-            Такое поведение переключения можно подавить, если добавить флаг в функцию <function>mopen</function>.
+            Когда используется функция <function>mgeti()</function>, проверяемые
+            числа преобразуются в тип целого числа <function>inttype</function>
+            в соответствии с выбранным форматом <varname>binFormat</varname>, а
+            затем возвращаются.
+            is used, parsed numbers are
+            converted into the <function>inttype</function> corresponding to
+            the chosen <varname>binFormat</varname> and then returned.
         </para>
         <para>
-            Форматы <literal>"l"</literal>, <literal>"d"</literal> и
-            <literal>"f"</literal> корректны только с функцией
-            <function>mget</function>.
+            Когда используется функция <function>mget()</function>, двоичные числа
+            проверяются в соответствии с форматом <varname>binFormat</varname>, то
+            в конце преобразуюся в восьмибайтные десятичные числа и затем возвращаются.
+            <warning>
+            Если, благодаря формату <literal>"ul*"</literal> или <literal>"l*"</literal>,
+            проверялись целые числа <literal>int64</literal> или <literal>uint64</literal>,
+            то их конечное преобразование в десятичные числа усекает их мантиссу
+            до 53 старших битов.
+            </warning>
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-file1 = fullfile(TMPDIR,'test1.bin');
-file2 = fullfile(TMPDIR,'test2.bin');
-fd1=mopen(file1,'wb');
-fd2=mopen(file2,'wb');
-mput(1996,'ull',fd1);
-mput(1996,'ull',fd2);
-mclose(fd1);
-mclose(fd2);
-
-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');
+binfile = TMPDIR+"/mgetest.bin";
+idF = mopen(binfile, "w+b");
+mput(int8(0:16),"uc");
+mseek(0);
+mgeti(1,"uc")  // ожидается 0
+mgeti(2,"uc")  // ожидается 1, 2
+[mgeti(1,"us"),  uint16(3 + 4*256)]
+mseek(3);      // возврат к предыдущей позиции на "3"
+[mgeti(1,"usb"), uint16(4 + 3*256)] // байты с изменёным порядком (прямой порядок)
+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 и int64 iс относительной точностью 1/2^64 = %eps/2^12
+// обрабатываются лучше, чем десятичные:
+    // Формирование n 64-битных чисел с битами №0-№63, установленными случайным образом:
+n = 5;
+b = grand(64,n,"uin",0,1);
+p = uint64(2).^ndgrid(0:63,1:n);
+x0 = sum(b.*p, "r");
+    // Запишем их в файл, а затем вновь прочитем их с помощью 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" принудительно управляет всеми 64 битами
+        // Теперь прочитаем их в том же режиме:
+        mseek(0);
+        xr = mgeti(n, usign+"l"+endian);
+        mclose(idF);
+        // Отобразим:
+        wrParse = usign + "l" + endian;
+        printf("    Запись в виде  ""%s""       Чтение в виде ""%s""\n", wrParse, wrParse);
+        [x' xr']
+    end
 end
-
-mclose(fd1);
-mclose(fd2);
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
         <simplelist type="inline">
             <member>
-                <link linkend="mclose">mclose</link>
-            </member>
-            <member>
-                <link linkend="meof">meof</link>
-            </member>
-            <member>
-                <link linkend="mfprintf">mfprintf</link>
-            </member>
-            <member>
-                <link linkend="fprintfMat">fprintfMat</link>
-            </member>
-            <member>
-                <link linkend="mfscanf">mfscanf</link>
-            </member>
-            <member>
-                <link linkend="fscanfMat">fscanfMat</link>
-            </member>
-            <member>
-                <link linkend="mgetl">mgetl</link>
-            </member>
-            <member>
-                <link linkend="mgetstr">mgetstr</link>
-            </member>
-            <member>
                 <link linkend="mopen">mopen</link>
             </member>
             <member>
-                <link linkend="mprintf">mprintf</link>
+                <link linkend="mclose">mclose</link>
             </member>
             <member>
                 <link linkend="mput">mput</link>
             </member>
             <member>
-                <link linkend="mputl">mputl</link>
+                <link linkend="mseek">mseek</link>
             </member>
             <member>
-                <link linkend="mputstr">mputstr</link>
+                <link linkend="mtell">mtell</link>
             </member>
             <member>
-                <link linkend="mseek">mseek</link>
+                <link linkend="meof">meof</link>
             </member>
             <member>
-                <link linkend="mtell">mtell</link>
+                <link linkend="readb">readb</link>
             </member>
             <member>
-                <link linkend="mdelete">mdelete</link>
+                <link linkend="read4b">read4b</link>
+            </member>
+            <member>
+                <link linkend="inttype">inttype</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                внедрена mgeti(,"ul*"|"l*") для чтения чисел типа uint64 или int64 больше 2<superscript>52</superscript>.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
-