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