1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="previous" href="Random.html">
<link rel="next" href="Set.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Arg" rel="Chapter" href="Arg.html">
<link title="Arith_status" rel="Chapter" href="Arith_status.html">
<link title="Array" rel="Chapter" href="Array.html">
<link title="ArrayLabels" rel="Chapter" href="ArrayLabels.html">
<link title="Big_int" rel="Chapter" href="Big_int.html">
<link title="Bigarray" rel="Chapter" href="Bigarray.html">
<link title="Buffer" rel="Chapter" href="Buffer.html">
<link title="Callback" rel="Chapter" href="Callback.html">
<link title="CamlinternalMod" rel="Chapter" href="CamlinternalMod.html">
<link title="CamlinternalOO" rel="Chapter" href="CamlinternalOO.html">
<link title="Char" rel="Chapter" href="Char.html">
<link title="Complex" rel="Chapter" href="Complex.html">
<link title="Condition" rel="Chapter" href="Condition.html">
<link title="Dbm" rel="Chapter" href="Dbm.html">
<link title="Digest" rel="Chapter" href="Digest.html">
<link title="Dynlink" rel="Chapter" href="Dynlink.html">
<link title="Event" rel="Chapter" href="Event.html">
<link title="Filename" rel="Chapter" href="Filename.html">
<link title="Format" rel="Chapter" href="Format.html">
<link title="Gc" rel="Chapter" href="Gc.html">
<link title="Genlex" rel="Chapter" href="Genlex.html">
<link title="Graphics" rel="Chapter" href="Graphics.html">
<link title="GraphicsX11" rel="Chapter" href="GraphicsX11.html">
<link title="Hashtbl" rel="Chapter" href="Hashtbl.html">
<link title="Int32" rel="Chapter" href="Int32.html">
<link title="Int64" rel="Chapter" href="Int64.html">
<link title="Lazy" rel="Chapter" href="Lazy.html">
<link title="Lexing" rel="Chapter" href="Lexing.html">
<link title="List" rel="Chapter" href="List.html">
<link title="ListLabels" rel="Chapter" href="ListLabels.html">
<link title="Map" rel="Chapter" href="Map.html">
<link title="Marshal" rel="Chapter" href="Marshal.html">
<link title="MoreLabels" rel="Chapter" href="MoreLabels.html">
<link title="Mutex" rel="Chapter" href="Mutex.html">
<link title="Nativeint" rel="Chapter" href="Nativeint.html">
<link title="Num" rel="Chapter" href="Num.html">
<link title="Obj" rel="Chapter" href="Obj.html">
<link title="Oo" rel="Chapter" href="Oo.html">
<link title="Parsing" rel="Chapter" href="Parsing.html">
<link title="Pervasives" rel="Chapter" href="Pervasives.html">
<link title="Printexc" rel="Chapter" href="Printexc.html">
<link title="Printf" rel="Chapter" href="Printf.html">
<link title="Queue" rel="Chapter" href="Queue.html">
<link title="Random" rel="Chapter" href="Random.html">
<link title="Scanf" rel="Chapter" href="Scanf.html">
<link title="Set" rel="Chapter" href="Set.html">
<link title="Sort" rel="Chapter" href="Sort.html">
<link title="Stack" rel="Chapter" href="Stack.html">
<link title="StdLabels" rel="Chapter" href="StdLabels.html">
<link title="Str" rel="Chapter" href="Str.html">
<link title="Stream" rel="Chapter" href="Stream.html">
<link title="String" rel="Chapter" href="String.html">
<link title="StringLabels" rel="Chapter" href="StringLabels.html">
<link title="Sys" rel="Chapter" href="Sys.html">
<link title="Thread" rel="Chapter" href="Thread.html">
<link title="ThreadUnix" rel="Chapter" href="ThreadUnix.html">
<link title="Unix" rel="Chapter" href="Unix.html">
<link title="UnixLabels" rel="Chapter" href="UnixLabels.html">
<link title="Weak" rel="Chapter" href="Weak.html"><title>Scanf</title>
</head>
<body>
<div class="navbar"><a href="Random.html">Previous</a>
<a href="index.html">Up</a>
<a href="Set.html">Next</a>
</div>
<center><h1>Module <a href="type_Scanf.html">Scanf</a></h1></center>
<br>
<pre><span class="keyword">module</span> Scanf: <code class="code"><span class="keyword">sig</span></code> <a href="Scanf.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Formatted input functions.<br>
<hr width="100%">
<pre><span class="keyword">module</span> <a href="Scanf.Scanning.html">Scanning</a>: <code class="code"><span class="keyword">sig</span></code> <a href="Scanf.Scanning.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Scanning buffers.
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONScan_failure"></a>Scan_failure <span class="keyword">of</span> <code class="type">string</code></pre>
<div class="info">
The exception that formatted input functions raise when the input
cannot be read according to the given format.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALbscanf"></a>bscanf : <code class="type"><a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a> -><br> ('a, <a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a>, 'b) <a href="Pervasives.html#TYPEformat">format</a> -> 'a -> 'b</code></pre><div class="info">
<code class="code">bscanf ib fmt f</code> reads tokens from the scanning buffer <code class="code">ib</code> according
to the format string <code class="code">fmt</code>, converts these tokens to values, and
applies the function <code class="code">f</code> to these values.
The result of this application of <code class="code">f</code> is the result of the whole construct.
<p>
For instance, if <code class="code">p</code> is the function <code class="code"><span class="keyword">fun</span> s i <span class="keywordsign">-></span> i + 1</code>, then
<code class="code"><span class="constructor">Scanf</span>.sscanf <span class="string">"x = 1"</span> <span class="string">"%s = %i"</span> p</code> returns <code class="code">2</code>.
<p>
The format is a character string which contains three types of
objects:<ul>
<li>plain characters, which are simply matched with the
characters of the input,</li>
<li>conversion specifications, each of which causes reading and
conversion of one argument for <code class="code">f</code>,</li>
<li>scanning indications to specify boundaries of tokens.</li>
</ul>
Among plain characters the space character (ASCII code 32) has a
special meaning: it matches ``whitespace'', that is any number of tab,
space, newline and carriage return characters. Hence, a space in the format
matches any amount of whitespace in the input.
<p>
Conversion specifications consist in the <code class="code">%</code> character, followed by
an optional flag, an optional field width, and followed by one or
two conversion characters. The conversion characters and their
meanings are:
<p>
<ul>
<li><code class="code">d</code>: reads an optionally signed decimal integer.</li>
<li><code class="code">i</code>: reads an optionally signed integer
(usual input formats for hexadecimal (<code class="code">0x[d]+</code> and <code class="code">0<span class="constructor">X</span>[d]+</code>),
octal (<code class="code">0o[d]+</code>), and binary <code class="code">0b[d]+</code> notations are understood).</li>
<li><code class="code">u</code>: reads an unsigned decimal integer.</li>
<li><code class="code">x</code> or <code class="code"><span class="constructor">X</span></code>: reads an unsigned hexadecimal integer.</li>
<li><code class="code">o</code>: reads an unsigned octal integer.</li>
<li><code class="code">s</code>: reads a string argument that spreads as much as possible,
until the next white space, the next scanning indication, or the
end-of-input is reached. Hence, this conversion always succeeds:
it returns an empty string if the bounding condition holds
when the scan begins.</li>
<li><code class="code"><span class="constructor">S</span></code>: reads a delimited string argument (delimiters and special
escaped characters follow the lexical conventions of Caml).</li>
<li><code class="code">c</code>: reads a single character. To test the current input character
without reading it, specify a null field width, i.e. use
specification <code class="code">%0c</code>. Raise <code class="code"><span class="constructor">Invalid_argument</span></code>, if the field width
specification is greater than 1.</li>
<li><code class="code"><span class="constructor">C</span></code>: reads a single delimited character (delimiters and special
escaped characters follow the lexical conventions of Caml).</li>
<li><code class="code">f</code>, <code class="code">e</code>, <code class="code"><span class="constructor">E</span></code>, <code class="code">g</code>, <code class="code"><span class="constructor">G</span></code>: reads an optionally signed
floating-point number in decimal notation, in the style <code class="code">dddd.ddd
e/<span class="constructor">E</span>+-dd</code>.</li>
<li><code class="code"><span class="constructor">F</span></code>: reads a floating point number according to the lexical
conventions of Caml (hence the decimal point is mandatory if the
exponent part is not mentioned).</li>
<li><code class="code"><span class="constructor">B</span></code>: reads a boolean argument (<code class="code"><span class="keyword">true</span></code> or <code class="code"><span class="keyword">false</span></code>).</li>
<li><code class="code">b</code>: reads a boolean argument (for backward compatibility; do not use
in new programs).</li>
<li><code class="code">ld</code>, <code class="code">li</code>, <code class="code">lu</code>, <code class="code">lx</code>, <code class="code">lX</code>, <code class="code">lo</code>: reads an <code class="code">int32</code> argument to
the format specified by the second letter (decimal, hexadecimal, etc).</li>
<li><code class="code">nd</code>, <code class="code">ni</code>, <code class="code">nu</code>, <code class="code">nx</code>, <code class="code">nX</code>, <code class="code">no</code>: reads a <code class="code">nativeint</code> argument to
the format specified by the second letter.</li>
<li><code class="code"><span class="constructor">Ld</span></code>, <code class="code"><span class="constructor">Li</span></code>, <code class="code"><span class="constructor">Lu</span></code>, <code class="code"><span class="constructor">Lx</span></code>, <code class="code"><span class="constructor">LX</span></code>, <code class="code"><span class="constructor">Lo</span></code>: reads an <code class="code">int64</code> argument to
the format specified by the second letter.</li>
<li><code class="code">[ range ]</code>: reads characters that matches one of the characters
mentioned in the range of characters <code class="code">range</code> (or not mentioned in
it, if the range starts with <code class="code">^</code>). Reads a <code class="code">string</code> that can be
empty, if no character in the input matches the range. The set of
characters from <code class="code">c1</code> to <code class="code">c2</code> (inclusively) is denoted by <code class="code">c1-c2</code>.
Hence, <code class="code">%[0-9]</code> returns a string representing a decimal number
or an empty string if no decimal digit is found; similarly,
<code class="code">%[\\048-\\057\\065-\\070]</code> returns a string of hexadecimal digits.
If a closing bracket appears in a range, it must occur as the
first character of the range (or just after the <code class="code">^</code> in case of
range negation); hence <code class="code">[]]</code> matches a <code class="code">]</code> character and
<code class="code">[^]]</code> matches any character that is not <code class="code">]</code>.</li>
<li><code class="code">{ fmt %}</code>: reads a format string argument to the format
specified by the internal format <code class="code">fmt</code>. The format string to be
read must have the same type as the internal format <code class="code">fmt</code>.
For instance, "%{%i%}" reads any format string that can read a value of
type <code class="code">int</code>; hence <code class="code"><span class="constructor">Scanf</span>.sscanf <span class="string">"fmt:\\\"number is %u\\\""</span> <span class="string">"fmt:%{%i%}"</span></code>
succeeds and returns the format string <code class="code"><span class="string">"number is %u"</span></code>.</li>
<li><code class="code">\( fmt %\)</code>: scanning format substitution.
Reads a format string to replace <code class="code">fmt</code>. The format string read
must have the same type as <code class="code">fmt</code>.</li>
<li><code class="code">l</code>: applies <code class="code">f</code> to the number of lines read so far.</li>
<li><code class="code">n</code>: applies <code class="code">f</code> to the number of characters read so far.</li>
<li><code class="code"><span class="constructor">N</span></code> or <code class="code"><span class="constructor">L</span></code>: applies <code class="code">f</code> to the number of tokens read so far.</li>
<li><code class="code">!</code>: matches the end of input condition.</li>
<li><code class="code">%</code>: matches one <code class="code">%</code> character in the input.</li>
</ul>
Following the <code class="code">%</code> character introducing a conversion, there may be
the special flag <code class="code">_</code>: the conversion that follows occurs as usual,
but the resulting value is discarded.
<p>
The field widths are composed of an optional integer literal
indicating the maximal width of the token to read.
For instance, <code class="code">%6d</code> reads an integer, having at most 6 decimal digits;
<code class="code">%4f</code> reads a float with at most 4 characters; and <code class="code">%8[\\000-\\255]</code>
returns the next 8 characters (or all the characters still available,
if less than 8 characters are available in the input).
<p>
Scanning indications appear just after the string conversions <code class="code">s</code>
and <code class="code">[ range ]</code> to delimit the end of the token. A scanning
indication is introduced by a <code class="code">@</code> character, followed by some
constant character <code class="code">c</code>. It means that the string token should end
just before the next matching <code class="code">c</code> (which is skipped). If no <code class="code">c</code>
character is encountered, the string token spreads as much as
possible. For instance, <code class="code"><span class="string">"%s@\t"</span></code> reads a string up to the next
tabulation character or to the end of input. If a scanning
indication <code class="code">@c</code> does not follow a string conversion, it is treated
as a plain <code class="code">c</code> character.
<p>
Raise <code class="code"><span class="constructor">Scanf</span>.<span class="constructor">Scan_failure</span></code> if the given input does not match the format.
<p>
Raise <code class="code"><span class="constructor">Failure</span></code> if a conversion to a number is not possible.
<p>
Raise <code class="code"><span class="constructor">End_of_file</span></code> if the end of input is encountered while some
more characters are needed to read the current conversion
specification (this means in particular that scanning a <code class="code">%s</code>
conversion never raises exception <code class="code"><span class="constructor">End_of_file</span></code>: if the end of
input is reached the conversion succeeds and simply returns <code class="code"><span class="string">""</span></code>).
<p>
Notes:
<p>
<ul>
<li>the scanning indications introduce slight differences in the
syntax of <code class="code"><span class="constructor">Scanf</span></code> format strings compared to those used by the
<code class="code"><span class="constructor">Printf</span></code> module. However, scanning indications are similar to those
of the <code class="code"><span class="constructor">Format</span></code> module; hence, when producing formatted text to be
scanned by <code class="code">!<span class="constructor">Scanf</span>.bscanf</code>, it is wise to use printing functions
from <code class="code"><span class="constructor">Format</span></code> (or, if you need to use functions from <code class="code"><span class="constructor">Printf</span></code>,
banish or carefully double check the format strings that contain
<code class="code"><span class="string">'@'</span></code> characters).</li>
</ul>
<ul>
<li>in addition to relevant digits, <code class="code"><span class="string">'_'</span></code> characters may appear
inside numbers (this is reminiscent to the usual Caml
conventions). If stricter scanning is desired, use the range
conversion facility instead of the number conversions.</li>
</ul>
<ul>
<li>the <code class="code">scanf</code> facility is not intended for heavy duty lexical
analysis and parsing. If it appears not expressive enough for your
needs, several alternative exists: regular expressions (module
<code class="code"><span class="constructor">Str</span></code>), stream parsers, <code class="code">ocamllex</code>-generated lexers,
<code class="code">ocamlyacc</code>-generated parsers.</li>
</ul>
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfscanf"></a>fscanf : <code class="type"><a href="Pervasives.html#TYPEin_channel">in_channel</a> -><br> ('a, <a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a>, 'b) <a href="Pervasives.html#TYPEformat">format</a> -> 'a -> 'b</code></pre><div class="info">
Same as <a href="Scanf.html#VALbscanf"><code class="code"><span class="constructor">Scanf</span>.bscanf</code></a>, but inputs from the given channel.
<p>
Warning: since all scanning functions operate from a scanning
buffer, be aware that each <code class="code">fscanf</code> invocation must allocate a new
fresh scanning buffer (unless careful use of partial evaluation in
the program). Hence, there are chances that some characters seem
to be skipped (in fact they are pending in the previously used
buffer). This happens in particular when calling <code class="code">fscanf</code> again
after a scan involving a format that necessitates some look ahead
(such as a format that ends by skipping whitespace in the input).
<p>
To avoid confusion, consider using <code class="code">bscanf</code> with an explicitly
created scanning buffer. Use for instance <code class="code"><span class="constructor">Scanning</span>.from_file f</code>
to allocate the scanning buffer reading from file <code class="code">f</code>.
<p>
This method is not only clearer it is also faster, since scanning
buffers to files are optimized for fast bufferized reading.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsscanf"></a>sscanf : <code class="type">string -> ('a, <a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a>, 'b) <a href="Pervasives.html#TYPEformat">format</a> -> 'a -> 'b</code></pre><div class="info">
Same as <a href="Scanf.html#VALbscanf"><code class="code"><span class="constructor">Scanf</span>.bscanf</code></a>, but inputs from the given string.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALscanf"></a>scanf : <code class="type">('a, <a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a>, 'b) <a href="Pervasives.html#TYPEformat">format</a> -> 'a -> 'b</code></pre><div class="info">
Same as <a href="Scanf.html#VALbscanf"><code class="code"><span class="constructor">Scanf</span>.bscanf</code></a>, but reads from the predefined scanning
buffer <a href="Scanf.Scanning.html#VALstdib"><code class="code"><span class="constructor">Scanf</span>.<span class="constructor">Scanning</span>.stdib</code></a> that is connected to <code class="code">stdin</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALkscanf"></a>kscanf : <code class="type"><a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a> -><br> (<a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a> -> exn -> 'a) -><br> ('b, <a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a>, 'a) <a href="Pervasives.html#TYPEformat">format</a> -> 'b -> 'a</code></pre><div class="info">
Same as <a href="Scanf.html#VALbscanf"><code class="code"><span class="constructor">Scanf</span>.bscanf</code></a>, but takes an additional function argument
<code class="code">ef</code> that is called in case of error: if the scanning process or
some conversion fails, the scanning function aborts and applies the
error handling function <code class="code">ef</code> to the scanning buffer and the
exception that aborted the scanning process.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALbscanf_format"></a>bscanf_format : <code class="type"><a href="Scanf.Scanning.html#TYPEscanbuf">Scanning.scanbuf</a> -><br> ('a, 'b, 'c, 'd) format4 -> (('a, 'b, 'c, 'd) format4 -> 'e) -> 'e</code></pre><div class="info">
<code class="code">bscanf_format ib fmt f</code> reads a <code class="code">format</code> argument to the format
specified by the second argument. The <code class="code">format</code> argument read in
buffer <code class="code">ib</code> must have the same type as <code class="code">fmt</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsscanf_format"></a>sscanf_format : <code class="type">string -> ('a, 'b, 'c, 'd) format4 -> ('a, 'b, 'c, 'd) format4</code></pre><div class="info">
<code class="code">sscanf_format ib fmt f</code> reads a <code class="code">format</code> argument to the format
specified by the second argument and returns it. The <code class="code">format</code>
argument read in string <code class="code">s</code> must have the same type as <code class="code">fmt</code>.<br>
</div>
</body></html>
|
