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 * Copyright (C) 2012 - 2016 - Scilab Enterprises
6 * Copyright (C) 2016 - Samuel GOUGEON
7 *
8 * This file is hereby licensed under the terms of the GNU GPL v2.0,
9 * pursuant to article 5.3.4 of the CeCILL v.2.1.
10 * This file was originally licensed under the terms of the CeCILL v2.1,
11 * and continues to be available under such terms.
12 * For more information, see the COPYING file which you should have received
13 * along with this program.
14 *
15 -->
16<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17    xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18    xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19    xmlns:scilab="http://www.scilab.org" xml:id="mget" xml:lang="ru">
20    <refnamediv>
21        <refname>mget</refname>
22        <refpurpose>
23            проверяет числа в двоичом файле и возвращает их в виде десятичных чисел
24        </refpurpose>
25    </refnamediv>
26    <refsynopsisdiv>
27        <title>Синтаксис</title>
28        <synopsis>
29            D = mget(nNumb)
30            D = mget(nNumb, binFormat)
31            D = mget(nNumb, binFormat, fileID)
32        </synopsis>
33    </refsynopsisdiv>
34    <refnamediv xml:id="mgeti">
35        <refname>mgeti</refname>
36        <refpurpose>
37            проверяет числа в двоичом файле и возвращает их в виде кодированных целых чисел
38        </refpurpose>
39    </refnamediv>
40    <refsynopsisdiv>
41        <title>Синтаксис</title>
42        <synopsis>
43            I = mgeti(nNumb)
44            I = mgeti(nNumb, binFormat)
45            I = mgeti(nNumb, binFormat, fileID)
46        </synopsis>
47    </refsynopsisdiv>
48    <refsection>
49        <title>Аргументы</title>
50        <variablelist>
51            <varlistentry>
52                <term>fileID</term>
53                <listitem>
54                    <para>
55                        идентификатор файла (целое число типа single), возвращаемое
56                        функцией <function>mopen</function> при открытии файла.
57                        По умолчанию используется последний открытый файл.
58                    <important>
59                        Файл должен быть открыт в режиме чтения двоичных данных
60                        с помощью инструкции <code>fileID = mopen(filename,'rb')</code>.
61                    </important>
62                    </para>
63                </listitem>
64            </varlistentry>
65            <varlistentry>
66                <term>nNumb</term>
67                <listitem>
68                    <para>
69                        Целое положительное число типа single: количество чисел,
70                        которые следует проверить и вернуть. Каждое число
71                        закодировано одним или несколькими байтами, в соответствии
72                        с используемым форматом <varname>binFormat</varname>.
73                        <note>
74                        Чтобы прочитать все числа, оставшиеся в файле, используйте
75                        достаточно большое значение <varname>nNumb</varname>.
76                        </note>
77                    </para>
78                </listitem>
79            </varlistentry>
80            <varlistentry>
81                <term>binFormat</term>
82                <listitem>
83                    <para>
84                        текстовое значение составленное из одного, двух или трёх
85                        символов-кодов: двоичный формат, используемый для проверки
86                        чисел в двоичном файле. Доступны следующие двоичные коды:
87                    <table>
88                        <tr valign="top">
89                            <td align="right">c</td>
90                            <td>: индивидуальные байты проверяются как целые числа
91                                типа <literal>int8</literal>;
92                            </td>
93                        </tr>
94                        <tr valign="top">
95                            <td align="right">uc</td>
96                            <td>: индивидуальные байты проверяются как целые
97                                беззнаковые положительные числа типа <literal>uint8</literal>;
98                            </td>
99                        </tr>
100                        <tr valign="top">
101                            <td align="right">s</td>
102                            <td>: двухбайтные блоки проверяются как целые числа типа
103                                <literal>int16</literal>;
104                            </td>
105                        </tr>
106                        <tr valign="top">
107                            <td align="right">us</td>
108                            <td>: двухбайтные блоки проверяются как целые беззнаковые
109                                положительные числа типа <literal>uint16</literal>;
110                            </td>
111                        </tr>
112                        <tr valign="top">
113                            <td align="right">i</td>
114                            <td>: четырёхбайтные блоки проверяются как целые числа
115                                типа <literal>int32</literal>
116                                (<emphasis role="bold">режим по умолчанию</emphasis>).
117                            </td>
118                        </tr>
119                        <tr valign="top">
120                            <td align="right">ui</td>
121                            <td>: четырёхбайтные блоки проверяются как целые
122                                беззнаковые положительные числа типа <literal>uint32</literal>;
123                            </td>
124                        </tr>
125                        <tr valign="top">
126                            <td align="right">l</td>
127                            <td>: восьмибайтные блоки проверяются как целые числа
128                                типа <literal>int64</literal>;
129                            </td>
130                        </tr>
131                        <tr valign="top">
132                            <td align="right">ul</td>
133                            <td>: восьмибайтные блоки проверяются как целые
134                                беззнаковые положительные числа типа
135                                <literal>uint64</literal>;
136                            </td>
137                        </tr>
138                        <tr>
139                            <td/>
140                            <td>
141                                Только с <function>mget()</function> :
142                            </td>
143                        </tr>
144                        <tr valign="top">
145                            <td align="right">f</td>
146                            <td>: четырёхбайтные блоки проверяются как десятичные
147                                числа "одинарной точности" (так называемые "числа
148                                с плавающей запятой", "<emphasis role="bold">f</emphasis>loats")
149                            </td>
150                        </tr>
151                        <tr valign="top">
152                            <td align="right">d</td>
153                            <td>: восьмибайтные блоки проверяются как десятичные
154                                ("<emphasis role="bold">d</emphasis>ecimal") числа.
155                            </td>
156                        </tr>
157                    </table>
158                    </para>
159                    <para>
160                        По умолчанию порядок байтов в блоке может быть установлен
161                        с помощью опции функции <function>mopen</function> при
162                        открытии файла. Этот порядок затем может принудительно
163                        быть использован с помощью настроечного флага функции
164                        <function>mget</function> или <function>mgeti</function>,
165                        который добавляется к <varname>binFormat</varname>:
166                        <table>
167                            <tr valign="top">
168                                <td align="right">..l :</td>
169                                <td>прямой порядок байтов (
170                                <emphasis role="bold">l</emphasis>ittle endian
171                                (младший байт идёт в начале блока);
172                                </td>
173                            </tr>
174                            <tr valign="top">
175                                <td align="right">..b :</td>
176                                <td>обратный порядок байтов (
177                                <emphasis role="bold">b</emphasis>ig endian
178                                (старший байт идёт в начале блока).
179                                </td>
180                            </tr>
181                        </table>
182                    </para>
183                </listitem>
184            </varlistentry>
185            <varlistentry>
186                <term>D</term>
187                <listitem>
188                    <para>
189                        Ряд из <varname>nNumb</varname> десятичных чисел
190                        (или имеющихся чисел, если достигнут конец файла).
191                    </para>
192                </listitem>
193            </varlistentry>
194            <varlistentry>
195                <term>I</term>
196                <listitem>
197                    <para>
198                        Ряд из <varname>nNumb</varname> закодированных целых чисел
199                        (или имеющихся чисел, если достигнут конец файла).
200                        Функция <function>inttype</function> возвращённых целых чисел
201                        зависит от используемого формата <varname>binFormat</varname>.
202                    </para>
203                </listitem>
204            </varlistentry>
205        </variablelist>
206    </refsection>
207    <refsection>
208        <title>Описание</title>
209        <para>
210            Функции <function>mget</function> и <function>mgeti</function> начинают
211            чтение байтов в указанном файле с текущей позиции внутреннего файлового
212            указателя. После чтения блока из <literal>N</literal> байтов
213            (<literal>N==1,2,4,8</literal> в соответствии с выбранным форматом
214            <varname>binFormat</varname>),
215            <itemizedlist>
216                <listitem>
217                    файловый указатель увеличивается на <literal>N</literal>
218                    байтов и устанавливается в начало следующего блока;
219                </listitem>
220                <listitem>
221                    блоки чтения идут в порядке, соответствующем выбранному или
222                    установленному по умолчанию режиму порядка байтов.
223                    Проверяемый блок затем сохраняется для возврата.
224                </listitem>
225            </itemizedlist>
226            Эти действия повторяются <varname>nNumb</varname> раз до тех пор,
227            пока не будет достигнут конец файла: в этом случае проверка файла
228            прекращается, неполный блок остаётся (если он есть), взводится статус
229            <literal>EOF</literal> и уже проверенные числа возвращаются.
230       </para>
231        <para>
232            Когда используется функция <function>mgeti()</function>, проверяемые
233            числа преобразуются в тип целого числа <function>inttype</function>
234            в соответствии с выбранным форматом <varname>binFormat</varname>, а
235            затем возвращаются.
236        </para>
237        <para>
238            Когда используется функция <function>mget()</function>, двоичные числа
239            проверяются в соответствии с форматом <varname>binFormat</varname>, то
240            в конце преобразуюся в восьмибайтные десятичные числа и затем возвращаются.
241            <warning>
242            Если, благодаря формату <literal>"ul*"</literal> или <literal>"l*"</literal>,
243            проверялись целые числа <literal>int64</literal> или <literal>uint64</literal>,
244            то их конечное преобразование в десятичные числа усекает их мантиссу
245            до 53 старших битов.
246            </warning>
247        </para>
248    </refsection>
249    <refsection>
250        <title>Примеры</title>
251        <programlisting role="example"><![CDATA[
252binfile = TMPDIR+"/mgetest.bin";
253idF = mopen(binfile, "w+b");
254mput(int8(0:16),"uc");
255mseek(0);
256mgeti(1,"uc")  // ожидается 0
257mgeti(2,"uc")  // ожидается 1, 2
258[mgeti(1,"us"),  uint16(3 + 4*256)]
259mseek(3);      // возврат к предыдущей позиции на "3"
260[mgeti(1,"usb"), uint16(4 + 3*256)] // байты с изменёным порядком (прямой порядок)
261mseek(0);
262[mgeti(1,"ui") , uint32(0 + 256*(1 + 256*(2 + 256*3)))]
263mseek(0);
264[mgeti(1,"uib"), uint32(3 + 256*(2 + 256*(1 + 256*0)))]
265mclose(idF);
266// целые числа uint64 и int64 iс относительной точностью 1/2^64 = %eps/2^12
267// обрабатываются лучше, чем десятичные:
268    // Формирование n 64-битных чисел с битами №0-№63, установленными случайным образом:
269n = 5;
270b = grand(64,n,"uin",0,1);
271p = uint64(2).^ndgrid(0:63,1:n);
272x0 = sum(b.*p, "r");
273    // Запишем их в файл, а затем вновь прочитем их с помощью mgeti():
274for 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" принудительно управляет всеми 64 битами
283        // Теперь прочитаем их в том же режиме:
284        mseek(0);
285        xr = mgeti(n, usign+"l"+endian);
286        mclose(idF);
287        // Отобразим:
288        wrParse = usign + "l" + endian;
289        printf("    Запись в виде  ""%s""       Чтение в виде ""%s""\n", wrParse, wrParse);
290        [x' xr']
291    end
292end
293 ]]></programlisting>
294    </refsection>
295    <refsection role="see also">
296        <title>Смотрите также</title>
297        <simplelist type="inline">
298            <member>
299                <link linkend="mopen">mopen</link>
300            </member>
301            <member>
302                <link linkend="mclose">mclose</link>
303            </member>
304            <member>
305                <link linkend="mput">mput</link>
306            </member>
307            <member>
308                <link linkend="mseek">mseek</link>
309            </member>
310            <member>
311                <link linkend="mtell">mtell</link>
312            </member>
313            <member>
314                <link linkend="meof">meof</link>
315            </member>
316            <member>
317                <link linkend="readb">readb</link>
318            </member>
319            <member>
320                <link linkend="read4b">read4b</link>
321            </member>
322            <member>
323                <link linkend="inttype">inttype</link>
324            </member>
325        </simplelist>
326    </refsection>
327    <refsection role="history">
328        <title>История</title>
329        <revhistory>
330            <revision>
331                <revnumber>6.1.1</revnumber>
332                <revdescription>
333                внедрена mgeti(,"ul*"|"l*") для чтения чисел типа uint64 или int64 больше 2<superscript>52</superscript>.
334                </revdescription>
335            </revision>
336        </revhistory>
337    </refsection>
338</refentry>
339