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