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