55069f2384ada17c8119303b9d9abba1ba433b9a
[scilab.git] / scilab / modules / fileio / help / ru_RU / 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  * 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             is used, parsed numbers are
237             converted into the <function>inttype</function> corresponding to
238             the chosen <varname>binFormat</varname> and then returned.
239         </para>
240         <para>
241             Когда используется функция <function>mget()</function>, двоичные числа
242             проверяются в соответствии с форматом <varname>binFormat</varname>, то
243             в конце преобразуюся в восьмибайтные десятичные числа и затем возвращаются.
244             <warning>
245             Если, благодаря формату <literal>"ul*"</literal> или <literal>"l*"</literal>,
246             проверялись целые числа <literal>int64</literal> или <literal>uint64</literal>,
247             то их конечное преобразование в десятичные числа усекает их мантиссу
248             до 53 старших битов.
249             </warning>
250         </para>
251     </refsection>
252     <refsection>
253         <title>Примеры</title>
254         <programlisting role="example"><![CDATA[
255 binfile = TMPDIR+"/mgetest.bin";
256 idF = mopen(binfile, "w+b");
257 mput(int8(0:16),"uc");
258 mseek(0);
259 mgeti(1,"uc")  // ожидается 0
260 mgeti(2,"uc")  // ожидается 1, 2
261 [mgeti(1,"us"),  uint16(3 + 4*256)]
262 mseek(3);      // возврат к предыдущей позиции на "3"
263 [mgeti(1,"usb"), uint16(4 + 3*256)] // байты с изменёным порядком (прямой порядок)
264 mseek(0);
265 [mgeti(1,"ui") , uint32(0 + 256*(1 + 256*(2 + 256*3)))]
266 mseek(0);
267 [mgeti(1,"uib"), uint32(3 + 256*(2 + 256*(1 + 256*0)))]
268 mclose(idF);
269 // целые числа uint64 и int64 iс относительной точностью 1/2^64 = %eps/2^12
270 // обрабатываются лучше, чем десятичные:
271     // Формирование n 64-битных чисел с битами №0-№63, установленными случайным образом:
272 n = 5;
273 b = grand(64,n,"uin",0,1);
274 p = uint64(2).^ndgrid(0:63,1:n);
275 x0 = sum(b.*p, "r");
276     // Запишем их в файл, а затем вновь прочитем их с помощью mgeti():
277 for usign = ["u" ""]
278     for endian = ["l" "b"]
279         binfile = TMPDIR+"/mgetiTestInt64.dat";
280         idF = mopen(binfile, "w+b");
281         x = x0;
282         if usign==""
283             x = int64(x);
284         end
285         mput(x,usign+"l"+endian)   // "l" принудительно управляет всеми 64 битами
286         // Теперь прочитаем их в том же режиме:
287         mseek(0);
288         xr = mgeti(n, usign+"l"+endian);
289         mclose(idF);
290         // Отобразим:
291         wrParse = usign + "l" + endian;
292         printf("    Запись в виде  ""%s""       Чтение в виде ""%s""\n", wrParse, wrParse);
293         [x' xr']
294     end
295 end
296  ]]></programlisting>
297     </refsection>
298     <refsection role="see also">
299         <title>Смотрите также</title>
300         <simplelist type="inline">
301             <member>
302                 <link linkend="mopen">mopen</link>
303             </member>
304             <member>
305                 <link linkend="mclose">mclose</link>
306             </member>
307             <member>
308                 <link linkend="mput">mput</link>
309             </member>
310             <member>
311                 <link linkend="mseek">mseek</link>
312             </member>
313             <member>
314                 <link linkend="mtell">mtell</link>
315             </member>
316             <member>
317                 <link linkend="meof">meof</link>
318             </member>
319             <member>
320                 <link linkend="readb">readb</link>
321             </member>
322             <member>
323                 <link linkend="read4b">read4b</link>
324             </member>
325             <member>
326                 <link linkend="inttype">inttype</link>
327             </member>
328         </simplelist>
329     </refsection>
330     <refsection role="history">
331         <title>История</title>
332         <revhistory>
333             <revision>
334                 <revnumber>6.1.0</revnumber>
335                 <revdescription>
336                 внедрена mgeti(,"ul*"|"l*") для чтения чисел типа uint64 или int64 больше 2<superscript>52</superscript>.
337                 </revdescription>
338             </revision>
339         </revhistory>
340     </refsection>
341 </refentry>