<!--
* 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>
-
projects / scilab.git / blobdiff