Get ride of the useless pubdate tag.
[scilab.git] / scilab / modules / fileio / help / en_US / 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  * ...
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <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" version="5.0-subset Scilab" xml:id="mget" xml:lang="en">
15   <refnamediv>
16     <refname>mget</refname>
17     <refpurpose>reads byte or word in a given binary format and convert to
18       double
19     </refpurpose>
20   </refnamediv>
21   <refnamediv xml:id="mgeti">
22     <refname>mgeti</refname>
23     <refpurpose>reads byte or word in a given binary format return an int
24       type
25     </refpurpose>
26   </refnamediv>
27   <refsynopsisdiv>
28     <title>Calling Sequence</title>
29     <synopsis>x=mget([n,type,fd])
30       x=mgeti([n,type,fd])
31     </synopsis>
32   </refsynopsisdiv>
33   <refsection>
34     <title>Arguments</title>
35     <variablelist>
36       <varlistentry>
37         <term>n</term>
38         <listitem>
39           <para>a positive scalar: The number of items to be read.</para>
40         </listitem>
41       </varlistentry>
42       <varlistentry>
43         <term>fd</term>
44         <listitem>
45           <para>
46             a scalar. The <literal>fd</literal> parameter returned by the
47             function <literal>mopen</literal>. -1 stands for last opened file.
48             Default value is -1.
49           </para>
50         </listitem>
51       </varlistentry>
52       <varlistentry>
53         <term>type</term>
54         <listitem>
55           <para>a string. Give the binary format used to write all the entries
56             of x.
57           </para>
58         </listitem>
59       </varlistentry>
60       <varlistentry>
61         <term>x</term>
62         <listitem>
63           <para>a vector of floating point or integer type numbers</para>
64         </listitem>
65       </varlistentry>
66     </variablelist>
67   </refsection>
68   <refsection>
69     <title>Description</title>
70     <para>
71       The <literal>mget</literal> function reads data in the input
72       specified by the stream parameter <literal>fd</literal> and returns a
73       vector of floating point data. The <literal>mgeti</literal> function reads
74       data in the input specified by the stream parameter <literal>fd</literal>
75       and returns a vector of integer data.
76     </para>
77     <para>Data is read at the position at which the file pointer is currently
78       pointing and advances the indicator appropriately.
79     </para>
80     <para>
81       The <literal>type</literal> parameter is a conversion specifier
82       which may be set to any of the following flag characters (with default
83       value "l"):
84     </para>
85     <para>
86       <emphasis role="bold">Note </emphasis>, On Windows, default behavior
87       is to skip byte 13 (0x0D). mopen should be called with the `b` option,
88       e.g. fd1=mopen(file1,'rb') , so that all bytes will be read without
89       exception.
90     </para>
91     <para>Data type:</para>
92     <variablelist>
93       <varlistentry>
94         <term>d</term>
95         <listitem>
96           <para>double</para>
97         </listitem>
98       </varlistentry>
99       <varlistentry>
100         <term>f</term>
101         <listitem>
102           <para>float</para>
103         </listitem>
104       </varlistentry>
105       <varlistentry>
106         <term>l</term>
107         <listitem>
108           <para>long</para>
109         </listitem>
110       </varlistentry>
111       <varlistentry>
112         <term>i</term>
113         <listitem>
114           <para>int</para>
115         </listitem>
116       </varlistentry>
117       <varlistentry>
118         <term>s</term>
119         <listitem>
120           <para>short</para>
121         </listitem>
122       </varlistentry>
123       <varlistentry>
124         <term>c</term>
125         <listitem>
126           <para>character</para>
127         </listitem>
128       </varlistentry>
129     </variablelist>
130     <para>Optional flag:</para>
131     <variablelist>
132       <varlistentry>
133         <term>u..</term>
134         <listitem>
135           <para>unsigned (in combination with one of the above types)</para>
136         </listitem>
137       </varlistentry>
138       <varlistentry>
139         <term>..l</term>
140         <listitem>
141           <para>little endian (in combination with one of the above types)</para>
142         </listitem>
143       </varlistentry>
144       <varlistentry>
145         <term>..b</term>
146         <listitem>
147           <para>big endian (in combination with one of the above types)</para>
148         </listitem>
149       </varlistentry>
150     </variablelist>
151     <para>Bytes read are automatically swapped if necessary (by checking
152       little=endian status).
153     </para>
154     <para>This default swapping behavior can be suprressed by adding a flag in
155       the mopen function.
156     </para>
157     <para>Formats "l", "d", and "f" are only valid with the mget
158       function.
159     </para>
160   </refsection>
161   <refsection>
162     <title>Examples</title>
163     <programlisting role="example"><![CDATA[ 
164 file1 = 'test1.bin';
165 file2 = 'test2.bin';
166 fd1=mopen(file1,'wb');
167 fd2=mopen(file2,'wb');
168 mput(1996,'ull',fd1);
169 mput(1996,'ull',fd2);
170 mclose(fd1);
171 mclose(fd2);
172
173 fd1=mopen(file1,'rb');
174 if 1996<>mget(1,'ull',fd1) ;write(%io(2),'Bug');end;
175 fd2=mopen(file2,'rb');
176 if 1996<>mget(1,'ull',fd2) ;write(%io(2),'Bug');end;
177 mclose(fd1);
178 mclose(fd2);
179  ]]></programlisting>
180   </refsection>
181   <refsection role="see also">
182     <title>See Also</title>
183     <simplelist type="inline">
184       <member>
185         <link linkend="mclose">mclose</link>
186       </member>
187       <member>
188         <link linkend="meof">meof</link>
189       </member>
190       <member>
191         <link linkend="mfprintf">mfprintf</link>
192       </member>
193       <member>
194         <link linkend="fprintfMat">fprintfMat</link>
195       </member>
196       <member>
197         <link linkend="mfscanf">mfscanf</link>
198       </member>
199       <member>
200         <link linkend="fscanfMat">fscanfMat</link>
201       </member>
202       <member>
203         <link linkend="mgetl">mgetl</link>
204       </member>
205       <member>
206         <link linkend="mgetstr">mgetstr</link>
207       </member>
208       <member>
209         <link linkend="mopen">mopen</link>
210       </member>
211       <member>
212         <link linkend="mprintf">mprintf</link>
213       </member>
214       <member>
215         <link linkend="mput">mput</link>
216       </member>
217       <member>
218         <link linkend="mputl">mputl</link>
219       </member>
220       <member>
221         <link linkend="mputstr">mputstr</link>
222       </member>
223       <member>
224         <link linkend="mscanf">mscanf</link>
225       </member>
226       <member>
227         <link linkend="mseek">mseek</link>
228       </member>
229       <member>
230         <link linkend="mtell">mtell</link>
231       </member>
232       <member>
233         <link linkend="mdelete">mdelete</link>
234       </member>
235     </simplelist>
236   </refsection>
237 </refentry>