1626 lines
24 KiB
HTML
1626 lines
24 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Scanf</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Scanf</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Scanf - Formatted input functions.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Scanf
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Scanf</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
Formatted input functions.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Introduction</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Functional input with format strings</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The module
|
|
<B>Scanf</B>
|
|
|
|
provides formatted input functions or scanners.
|
|
<P>
|
|
The formatted input functions can read from any kind of input, including
|
|
strings, files, or anything that can return characters. The more general
|
|
source of characters is named a formatted input channel (or scanning buffer) and has type
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
. The more general
|
|
formatted input function reads from any scanning buffer and is named
|
|
<B>bscanf</B>
|
|
|
|
.
|
|
<P>
|
|
Generally speaking, the formatted input functions have 3 arguments:
|
|
<P>
|
|
-the first argument is a source of characters for the input,
|
|
<P>
|
|
-the second argument is a format string that specifies the values to
|
|
read,
|
|
<P>
|
|
-the third argument is a receiver function that is applied to the
|
|
values read.
|
|
<P>
|
|
Hence, a typical call to the formatted input function
|
|
<B>Scanf.bscanf</B>
|
|
|
|
is
|
|
<B>bscanf ic fmt f</B>
|
|
|
|
, where:
|
|
<P>
|
|
<P>
|
|
-
|
|
<B>ic</B>
|
|
|
|
is a source of characters (typically a formatted input channel with type
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
),
|
|
<P>
|
|
<P>
|
|
-
|
|
<B>fmt</B>
|
|
|
|
is a format string (the same format strings as those used to print
|
|
material with module
|
|
<B>Printf</B>
|
|
|
|
or
|
|
<B>Format</B>
|
|
|
|
),
|
|
<P>
|
|
<P>
|
|
-
|
|
<B>f</B>
|
|
|
|
is a function that has as many arguments as the number of values to
|
|
read in the input according to
|
|
<B>fmt</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>A simple example</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
As suggested above, the expression
|
|
<B>bscanf ic %d f</B>
|
|
|
|
reads a decimal
|
|
integer
|
|
<B>n</B>
|
|
|
|
from the source of characters
|
|
<B>ic</B>
|
|
|
|
and returns
|
|
<B>f n</B>
|
|
|
|
.
|
|
<P>
|
|
For instance,
|
|
<P>
|
|
<P>
|
|
-if we use
|
|
<B>stdin</B>
|
|
|
|
as the source of characters (
|
|
<B>Scanf.Scanning.stdin</B>
|
|
|
|
is
|
|
the predefined formatted input channel that reads from standard input),
|
|
<P>
|
|
<P>
|
|
-if we define the receiver
|
|
<B>f</B>
|
|
|
|
as
|
|
<B>let f x = x + 1</B>
|
|
|
|
,
|
|
<P>
|
|
then
|
|
<B>bscanf Scanning.stdin %d f</B>
|
|
|
|
reads an integer
|
|
<B>n</B>
|
|
|
|
from the
|
|
standard input and returns
|
|
<B>f n</B>
|
|
|
|
(that is
|
|
<B>n + 1</B>
|
|
|
|
). Thus, if we
|
|
evaluate
|
|
<B>bscanf stdin %d f</B>
|
|
|
|
, and then enter
|
|
<B>41</B>
|
|
|
|
at the
|
|
keyboard, the result we get is
|
|
<B>42</B>
|
|
|
|
.
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Formatted input as a functional feature</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The OCaml scanning facility is reminiscent of the corresponding C feature.
|
|
However, it is also largely different, simpler, and yet more powerful:
|
|
the formatted input functions are higher-order functionals and the
|
|
parameter passing mechanism is just the regular function application not
|
|
the variable assignment based mechanism which is typical for formatted
|
|
input in imperative languages; the OCaml format strings also feature
|
|
useful additions to easily define complex tokens; as expected within a
|
|
functional programming language, the formatted input functions also
|
|
support polymorphism, in particular arbitrary interaction with
|
|
polymorphic user-defined scanners. Furthermore, the OCaml formatted input
|
|
facility is fully type-checked at compile time.
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Formatted input channel</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>module Scanning : </I>
|
|
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Type of formatted input functions</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type </I>
|
|
|
|
<B>('a, 'b, 'c, 'd)</B>
|
|
|
|
<I>scanner </I>
|
|
|
|
=
|
|
<B>('a, Scanning.in_channel, 'b, 'c, 'a -> 'd, 'd) format6 -> 'c</B>
|
|
|
|
<P>
|
|
<P>
|
|
The type of formatted input scanners:
|
|
<B>('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
is the type of a formatted input function that reads from some
|
|
formatted input channel according to some format string; more
|
|
precisely, if
|
|
<B>scan</B>
|
|
|
|
is some formatted input function, then
|
|
<B>scan</B>
|
|
|
|
<B>ic fmt f</B>
|
|
|
|
applies
|
|
<B>f</B>
|
|
|
|
to all the arguments specified by format
|
|
string
|
|
<B>fmt</B>
|
|
|
|
, when
|
|
<B>scan</B>
|
|
|
|
has read those arguments from the
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
formatted input channel
|
|
<B>ic</B>
|
|
|
|
.
|
|
<P>
|
|
For instance, the
|
|
<B>Scanf.scanf</B>
|
|
|
|
function below has type
|
|
<B>('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
, since it is a formatted input function that
|
|
reads from
|
|
<B>Scanf.Scanning.stdin</B>
|
|
|
|
:
|
|
<B>scanf fmt f</B>
|
|
|
|
applies
|
|
<B>f</B>
|
|
|
|
to the arguments
|
|
specified by
|
|
<B>fmt</B>
|
|
|
|
, reading those arguments from
|
|
<B>stdin</B>
|
|
|
|
as
|
|
expected.
|
|
<P>
|
|
If the format
|
|
<B>fmt</B>
|
|
|
|
has some
|
|
<B>%r</B>
|
|
|
|
indications, the corresponding
|
|
formatted input functions must be provided before receiver function
|
|
<B>f</B>
|
|
|
|
. For instance, if
|
|
<B>read_elem</B>
|
|
|
|
is an input function for values of type
|
|
<B>t</B>
|
|
|
|
, then
|
|
<B>bscanf ic %r; read_elem f</B>
|
|
|
|
reads a value
|
|
<B>v</B>
|
|
|
|
of type
|
|
<B>t</B>
|
|
|
|
followed by a
|
|
<B>';'</B>
|
|
|
|
character, and returns
|
|
<B>f v</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.10.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>exception Scan_failure </I>
|
|
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
When the input can not be read according to the format string
|
|
specification, formatted input functions typically raise exception
|
|
<B>Scan_failure</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>The general formatted input function</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val bscanf </I>
|
|
|
|
:
|
|
<B>Scanning.in_channel -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<B>bscanf ic fmt r1 ... rN f</B>
|
|
|
|
reads characters from the
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
formatted input channel
|
|
<B>ic</B>
|
|
|
|
and converts them to
|
|
values according to format string
|
|
<B>fmt</B>
|
|
|
|
.
|
|
As a final step, receiver function
|
|
<B>f</B>
|
|
|
|
is applied to the values read and
|
|
gives the result of the
|
|
<B>bscanf</B>
|
|
|
|
call.
|
|
<P>
|
|
For instance, if
|
|
<B>f</B>
|
|
|
|
is the function
|
|
<B>fun s i -> i + 1</B>
|
|
|
|
, then
|
|
<B>Scanf.sscanf x= 1 %s = %i f</B>
|
|
|
|
returns
|
|
<B>2</B>
|
|
|
|
.
|
|
<P>
|
|
Arguments
|
|
<B>r1</B>
|
|
|
|
to
|
|
<B>rN</B>
|
|
|
|
are user-defined input functions that read the
|
|
argument corresponding to the
|
|
<B>%r</B>
|
|
|
|
conversions specified in the format
|
|
string.
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Format string description</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The format string is a character string which contains three types of
|
|
objects:
|
|
<P>
|
|
-plain characters, which are simply matched with the characters of the
|
|
input (with a special case for space and line feed, see
|
|
<B>Scanf.space</B>
|
|
|
|
),
|
|
<P>
|
|
-conversion specifications, each of which causes reading and conversion of
|
|
one argument for the function
|
|
<B>f</B>
|
|
|
|
(see
|
|
<B>Scanf.conversion</B>
|
|
|
|
),
|
|
<P>
|
|
-scanning indications to specify boundaries of tokens
|
|
(see scanning
|
|
<B>Scanf.indication</B>
|
|
|
|
).
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H3>The space character in format strings</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
As mentioned above, a plain character in the format string is just
|
|
matched with the next character of the input; however, two characters are
|
|
special exceptions to this rule: the space character (
|
|
<B>' '</B>
|
|
|
|
or ASCII code
|
|
32) and the line feed character (
|
|
<B>'\n'</B>
|
|
|
|
or ASCII code 10).
|
|
A space does not match a single space character, but any amount of
|
|
'whitespace' in the input. More precisely, a space inside the format
|
|
string matches any number of tab, space, line feed and carriage
|
|
return characters. Similarly, a line feed character in the format string
|
|
matches either a single line feed or a carriage return followed by a line
|
|
feed.
|
|
<P>
|
|
Matching any amount of whitespace, a space in the format string
|
|
also matches no amount of whitespace at all; hence, the call
|
|
<B>bscanf ib</B>
|
|
|
|
<B>Price = %d $ (fun p -> p)</B>
|
|
|
|
succeeds and returns
|
|
<B>1</B>
|
|
|
|
when reading an
|
|
input with various whitespace in it, such as
|
|
<B>Price = 1 $</B>
|
|
|
|
,
|
|
<B>Price = 1 $</B>
|
|
|
|
, or even
|
|
<B>Price=1$</B>
|
|
|
|
.
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Conversion specifications in format strings</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Conversion specifications consist in the
|
|
<B>%</B>
|
|
|
|
character, followed by
|
|
an optional flag, an optional field width, and followed by one or
|
|
two conversion characters.
|
|
<P>
|
|
The conversion characters and their meanings are:
|
|
<P>
|
|
<P>
|
|
-
|
|
<B>d</B>
|
|
|
|
: reads an optionally signed decimal integer (
|
|
<B>0-9</B>
|
|
|
|
+).
|
|
<P>
|
|
-
|
|
<B>i</B>
|
|
|
|
: reads an optionally signed integer
|
|
(usual input conventions for decimal (
|
|
<B>0-9</B>
|
|
|
|
+), hexadecimal
|
|
(
|
|
<B>0x[0-9a-f]+</B>
|
|
|
|
and
|
|
<B>0X[0-9A-F]+</B>
|
|
|
|
), octal (
|
|
<B>0o[0-7]+</B>
|
|
|
|
), and binary
|
|
(
|
|
<B>0b[0-1]+</B>
|
|
|
|
) notations are understood).
|
|
<P>
|
|
-
|
|
<B>u</B>
|
|
|
|
: reads an unsigned decimal integer.
|
|
<P>
|
|
-
|
|
<B>x</B>
|
|
|
|
or
|
|
<B>X</B>
|
|
|
|
: reads an unsigned hexadecimal integer (
|
|
<B>[0-9a-fA-F]+</B>
|
|
|
|
).
|
|
<P>
|
|
-
|
|
<B>o</B>
|
|
|
|
: reads an unsigned octal integer (
|
|
<B>[0-7]+</B>
|
|
|
|
).
|
|
<P>
|
|
-
|
|
<B>s</B>
|
|
|
|
: reads a string argument that spreads as much as possible, until the
|
|
following bounding condition holds:
|
|
<P>
|
|
-a whitespace has been found (see
|
|
<B>Scanf.space</B>
|
|
|
|
),
|
|
<P>
|
|
-a scanning indication (see scanning
|
|
<B>Scanf.indication</B>
|
|
|
|
) has been
|
|
encountered,
|
|
<P>
|
|
-the end-of-input has been reached.
|
|
<P>
|
|
Hence, this conversion always succeeds: it returns an empty
|
|
string if the bounding condition holds when the scan begins.
|
|
<P>
|
|
-
|
|
<B>S</B>
|
|
|
|
: reads a delimited string argument (delimiters and special
|
|
escaped characters follow the lexical conventions of OCaml).
|
|
<P>
|
|
-
|
|
<B>c</B>
|
|
|
|
: reads a single character. To test the current input character
|
|
without reading it, specify a null field width, i.e. use
|
|
specification
|
|
<B>%0c</B>
|
|
|
|
. Raise
|
|
<B>Invalid_argument</B>
|
|
|
|
, if the field width
|
|
specification is greater than 1.
|
|
<P>
|
|
-
|
|
<B>C</B>
|
|
|
|
: reads a single delimited character (delimiters and special
|
|
escaped characters follow the lexical conventions of OCaml).
|
|
<P>
|
|
-
|
|
<B>f</B>
|
|
|
|
,
|
|
<B>e</B>
|
|
|
|
,
|
|
<B>E</B>
|
|
|
|
,
|
|
<B>g</B>
|
|
|
|
,
|
|
<B>G</B>
|
|
|
|
: reads an optionally signed
|
|
floating-point number in decimal notation, in the style
|
|
<B>dddd.ddd</B>
|
|
|
|
<B>e/E+-dd</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>h</B>
|
|
|
|
,
|
|
<B>H</B>
|
|
|
|
: reads an optionally signed floating-point number
|
|
in hexadecimal notation.
|
|
<P>
|
|
-
|
|
<B>F</B>
|
|
|
|
: reads a floating point number according to the lexical
|
|
conventions of OCaml (hence the decimal point is mandatory if the
|
|
exponent part is not mentioned).
|
|
<P>
|
|
-
|
|
<B>B</B>
|
|
|
|
: reads a boolean argument (
|
|
<B>true</B>
|
|
|
|
or
|
|
<B>false</B>
|
|
|
|
).
|
|
<P>
|
|
-
|
|
<B>b</B>
|
|
|
|
: reads a boolean argument (for backward compatibility; do not use
|
|
in new programs).
|
|
<P>
|
|
-
|
|
<B>ld</B>
|
|
|
|
,
|
|
<B>li</B>
|
|
|
|
,
|
|
<B>lu</B>
|
|
|
|
,
|
|
<B>lx</B>
|
|
|
|
,
|
|
<B>lX</B>
|
|
|
|
,
|
|
<B>lo</B>
|
|
|
|
: reads an
|
|
<B>int32</B>
|
|
|
|
argument to
|
|
the format specified by the second letter for regular integers.
|
|
<P>
|
|
-
|
|
<B>nd</B>
|
|
|
|
,
|
|
<B>ni</B>
|
|
|
|
,
|
|
<B>nu</B>
|
|
|
|
,
|
|
<B>nx</B>
|
|
|
|
,
|
|
<B>nX</B>
|
|
|
|
,
|
|
<B>no</B>
|
|
|
|
: reads a
|
|
<B>nativeint</B>
|
|
|
|
argument to
|
|
the format specified by the second letter for regular integers.
|
|
<P>
|
|
-
|
|
<B>Ld</B>
|
|
|
|
,
|
|
<B>Li</B>
|
|
|
|
,
|
|
<B>Lu</B>
|
|
|
|
,
|
|
<B>Lx</B>
|
|
|
|
,
|
|
<B>LX</B>
|
|
|
|
,
|
|
<B>Lo</B>
|
|
|
|
: reads an
|
|
<B>int64</B>
|
|
|
|
argument to
|
|
the format specified by the second letter for regular integers.
|
|
<P>
|
|
-
|
|
<B>[ range ]</B>
|
|
|
|
: reads characters that matches one of the characters
|
|
mentioned in the range of characters
|
|
<B>range</B>
|
|
|
|
(or not mentioned in
|
|
it, if the range starts with
|
|
<B>^</B>
|
|
|
|
). Reads a
|
|
<B>string</B>
|
|
|
|
that can be
|
|
empty, if the next input character does not match the range. The set of
|
|
characters from
|
|
<B>c1</B>
|
|
|
|
to
|
|
<B>c2</B>
|
|
|
|
(inclusively) is denoted by
|
|
<B>c1-c2</B>
|
|
|
|
.
|
|
Hence,
|
|
<B>%[0-9]</B>
|
|
|
|
returns a string representing a decimal number
|
|
or an empty string if no decimal digit is found; similarly,
|
|
<B>%[0-9a-f]</B>
|
|
|
|
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
|
|
<B>^</B>
|
|
|
|
in case of
|
|
range negation); hence
|
|
<B>[]]</B>
|
|
|
|
matches a
|
|
<B>]</B>
|
|
|
|
character and
|
|
<B>[^]]</B>
|
|
|
|
matches any character that is not
|
|
<B>]</B>
|
|
|
|
.
|
|
Use
|
|
<B>%%</B>
|
|
|
|
and
|
|
<B>%@</B>
|
|
|
|
to include a
|
|
<B>%</B>
|
|
|
|
or a
|
|
<B>@</B>
|
|
|
|
in a range.
|
|
<P>
|
|
-
|
|
<B>r</B>
|
|
|
|
: user-defined reader. Takes the next
|
|
<B>ri</B>
|
|
|
|
formatted input
|
|
function and applies it to the scanning buffer
|
|
<B>ib</B>
|
|
|
|
to read the
|
|
next argument. The input function
|
|
<B>ri</B>
|
|
|
|
must therefore have type
|
|
<B>Scanning.in_channel -> 'a</B>
|
|
|
|
and the argument read has type
|
|
<B>'a</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>{ fmt %}</B>
|
|
|
|
: reads a format string argument. The format string
|
|
read must have the same type as the format string specification
|
|
<B>fmt</B>
|
|
|
|
. For instance,
|
|
<B>%{ %i %}</B>
|
|
|
|
reads any format string that
|
|
can read a value of type
|
|
<B>int</B>
|
|
|
|
; hence, if
|
|
<B>s</B>
|
|
|
|
is the string
|
|
<B>fmt:\number is %u\</B>
|
|
|
|
, then
|
|
<B>Scanf.sscanf s fmt: %{%i%}</B>
|
|
|
|
succeeds and returns the format string
|
|
<B>number is %u</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>( fmt %)</B>
|
|
|
|
: scanning sub-format substitution.
|
|
Reads a format string
|
|
<B>rf</B>
|
|
|
|
in the input, then goes on scanning with
|
|
<B>rf</B>
|
|
|
|
instead of scanning with
|
|
<B>fmt</B>
|
|
|
|
.
|
|
The format string
|
|
<B>rf</B>
|
|
|
|
must have the same type as the format string
|
|
specification
|
|
<B>fmt</B>
|
|
|
|
that it replaces.
|
|
For instance,
|
|
<B>%( %i %)</B>
|
|
|
|
reads any format string that can read a value
|
|
of type
|
|
<B>int</B>
|
|
|
|
.
|
|
The conversion returns the format string read
|
|
<B>rf</B>
|
|
|
|
, and then a value
|
|
read using
|
|
<B>rf</B>
|
|
|
|
.
|
|
Hence, if
|
|
<B>s</B>
|
|
|
|
is the string
|
|
<B>\%4d\1234.00</B>
|
|
|
|
, then
|
|
<B>Scanf.sscanf s %(%i%) (fun fmt i -> fmt, i)</B>
|
|
|
|
evaluates to
|
|
<B>(%4d, 1234)</B>
|
|
|
|
.
|
|
This behaviour is not mere format substitution, since the conversion
|
|
returns the format string read as additional argument. If you need
|
|
pure format substitution, use special flag
|
|
<B>_</B>
|
|
|
|
to discard the
|
|
extraneous argument: conversion
|
|
<B>%_( fmt %)</B>
|
|
|
|
reads a format string
|
|
<B>rf</B>
|
|
|
|
and then behaves the same as format string
|
|
<B>rf</B>
|
|
|
|
. Hence, if
|
|
<B>s</B>
|
|
|
|
is
|
|
the string
|
|
<B>\%4d\1234.00</B>
|
|
|
|
, then
|
|
<B>Scanf.sscanf s %_(%i%)</B>
|
|
|
|
is
|
|
simply equivalent to
|
|
<B>Scanf.sscanf 1234.00 %4d</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>l</B>
|
|
|
|
: returns the number of lines read so far.
|
|
<P>
|
|
-
|
|
<B>n</B>
|
|
|
|
: returns the number of characters read so far.
|
|
<P>
|
|
-
|
|
<B>N</B>
|
|
|
|
or
|
|
<B>L</B>
|
|
|
|
: returns the number of tokens read so far.
|
|
<P>
|
|
-
|
|
<B>!</B>
|
|
|
|
: matches the end of input condition.
|
|
<P>
|
|
-
|
|
<B>%</B>
|
|
|
|
: matches one
|
|
<B>%</B>
|
|
|
|
character in the input.
|
|
<P>
|
|
-
|
|
<B>@</B>
|
|
|
|
: matches one
|
|
<B>@</B>
|
|
|
|
character in the input.
|
|
<P>
|
|
-
|
|
<B>,</B>
|
|
|
|
: does nothing.
|
|
<P>
|
|
Following the
|
|
<B>%</B>
|
|
|
|
character that introduces a conversion, there may be
|
|
the special flag
|
|
<B>_</B>
|
|
|
|
: the conversion that follows occurs as usual,
|
|
but the resulting value is discarded.
|
|
For instance, if
|
|
<B>f</B>
|
|
|
|
is the function
|
|
<B>fun i -> i + 1</B>
|
|
|
|
, and
|
|
<B>s</B>
|
|
|
|
is the
|
|
string
|
|
<B>x = 1</B>
|
|
|
|
, then
|
|
<B>Scanf.sscanf s %_s = %i f</B>
|
|
|
|
returns
|
|
<B>2</B>
|
|
|
|
.
|
|
<P>
|
|
The field width is composed of an optional integer literal
|
|
indicating the maximal width of the token to read.
|
|
For instance,
|
|
<B>%6d</B>
|
|
|
|
reads an integer, having at most 6 decimal digits;
|
|
<B>%4f</B>
|
|
|
|
reads a float with at most 4 characters; and
|
|
<B>%8[\000-\255]</B>
|
|
|
|
returns the next 8 characters (or all the characters still available,
|
|
if fewer than 8 characters are available in the input).
|
|
<P>
|
|
Notes:
|
|
<P>
|
|
<P>
|
|
-as mentioned above, a
|
|
<B>%s</B>
|
|
|
|
conversion always succeeds, even if there is
|
|
nothing to read in the input: in this case, it simply returns
|
|
<B></B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
-in addition to the relevant digits,
|
|
<B>'_'</B>
|
|
|
|
characters may appear
|
|
inside numbers (this is reminiscent to the usual OCaml lexical
|
|
conventions). If stricter scanning is desired, use the range
|
|
conversion facility instead of the number conversions.
|
|
<P>
|
|
<P>
|
|
-the
|
|
<B>scanf</B>
|
|
|
|
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
|
|
<B>Str</B>
|
|
|
|
), stream parsers,
|
|
<B>ocamllex</B>
|
|
|
|
-generated lexers,
|
|
<B>ocamlyacc</B>
|
|
|
|
-generated parsers.
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Scanning indications in format strings</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Scanning indications appear just after the string conversions
|
|
<B>%s</B>
|
|
|
|
and
|
|
<B>%[ range ]</B>
|
|
|
|
to delimit the end of the token. A scanning
|
|
indication is introduced by a
|
|
<B>@</B>
|
|
|
|
character, followed by some
|
|
plain character
|
|
<B>c</B>
|
|
|
|
. It means that the string token should end
|
|
just before the next matching
|
|
<B>c</B>
|
|
|
|
(which is skipped). If no
|
|
<B>c</B>
|
|
|
|
character is encountered, the string token spreads as much as
|
|
possible. For instance,
|
|
<B>%s@\t</B>
|
|
|
|
reads a string up to the next
|
|
tab character or to the end of input. If a
|
|
<B>@</B>
|
|
|
|
character appears
|
|
anywhere else in the format string, it is treated as a plain character.
|
|
<P>
|
|
Note:
|
|
<P>
|
|
<P>
|
|
-As usual in format strings,
|
|
<B>%</B>
|
|
|
|
and
|
|
<B>@</B>
|
|
|
|
characters must be escaped
|
|
using
|
|
<B>%%</B>
|
|
|
|
and
|
|
<B>%@</B>
|
|
|
|
; this rule still holds within range specifications
|
|
and scanning indications.
|
|
For instance, format
|
|
<B>%s@%%</B>
|
|
|
|
reads a string up to the next
|
|
<B>%</B>
|
|
|
|
character, and format
|
|
<B>%s@%@</B>
|
|
|
|
reads a string up to the next
|
|
<B>@</B>
|
|
|
|
.
|
|
<P>
|
|
-The scanning indications introduce slight differences in the syntax of
|
|
<B>Scanf</B>
|
|
|
|
format strings, compared to those used for the
|
|
<B>Printf</B>
|
|
|
|
module. However, the scanning indications are similar to those used in
|
|
the
|
|
<B>Format</B>
|
|
|
|
module; hence, when producing formatted text to be scanned
|
|
by
|
|
<B>Scanf.bscanf</B>
|
|
|
|
, it is wise to use printing functions from the
|
|
<B>Format</B>
|
|
|
|
module (or, if you need to use functions from
|
|
<B>Printf</B>
|
|
|
|
, banish
|
|
or carefully double check the format strings that contain
|
|
<B>'@'</B>
|
|
|
|
characters).
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Exceptions during scanning</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Scanners may raise the following exceptions when the input cannot be read
|
|
according to the format string:
|
|
<P>
|
|
<P>
|
|
-Raise
|
|
<B>Scanf.Scan_failure</B>
|
|
|
|
if the input does not match the format.
|
|
<P>
|
|
<P>
|
|
-Raise
|
|
<B>Failure</B>
|
|
|
|
if a conversion to a number is not possible.
|
|
<P>
|
|
<P>
|
|
-Raise
|
|
<B>End_of_file</B>
|
|
|
|
if the end of input is encountered while some more
|
|
characters are needed to read the current conversion specification.
|
|
<P>
|
|
<P>
|
|
-Raise
|
|
<B>Invalid_argument</B>
|
|
|
|
if the format string is invalid.
|
|
<P>
|
|
Note:
|
|
<P>
|
|
<P>
|
|
-as a consequence, scanning a
|
|
<B>%s</B>
|
|
|
|
conversion never raises exception
|
|
<B>End_of_file</B>
|
|
|
|
: if the end of input is reached the conversion succeeds and
|
|
simply returns the characters read so far, or
|
|
<B></B>
|
|
|
|
if none were ever read.
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Specialised formatted input functions</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val sscanf </I>
|
|
|
|
:
|
|
<B>string -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Scanf.bscanf</B>
|
|
|
|
, but reads from the given string.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val scanf </I>
|
|
|
|
:
|
|
<B>('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Scanf.bscanf</B>
|
|
|
|
, but reads from the predefined formatted input
|
|
channel
|
|
<B>Scanf.Scanning.stdin</B>
|
|
|
|
that is connected to
|
|
<B>stdin</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val kscanf </I>
|
|
|
|
:
|
|
<B>Scanning.in_channel -></B>
|
|
|
|
<B>(Scanning.in_channel -> exn -> 'd) -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Scanf.bscanf</B>
|
|
|
|
, but takes an additional function argument
|
|
<B>ef</B>
|
|
|
|
that is called in case of error: if the scanning process or
|
|
some conversion fails, the scanning function aborts and calls the
|
|
error handling function
|
|
<B>ef</B>
|
|
|
|
with the formatted input channel and the
|
|
exception that aborted the scanning process as arguments.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val ksscanf </I>
|
|
|
|
:
|
|
<B>string -></B>
|
|
|
|
<B>(Scanning.in_channel -> exn -> 'd) -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Scanf.kscanf</B>
|
|
|
|
but reads from the given string.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Reading format strings from input</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val bscanf_format </I>
|
|
|
|
:
|
|
<B>Scanning.in_channel -></B>
|
|
|
|
<B>('a, 'b, 'c, 'd, 'e, 'f) format6 -></B>
|
|
|
|
<B>(('a, 'b, 'c, 'd, 'e, 'f) format6 -> 'g) -> 'g</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>bscanf_format ic fmt f</B>
|
|
|
|
reads a format string token from the formatted
|
|
input channel
|
|
<B>ic</B>
|
|
|
|
, according to the given format string
|
|
<B>fmt</B>
|
|
|
|
, and
|
|
applies
|
|
<B>f</B>
|
|
|
|
to the resulting format string value.
|
|
Raise
|
|
<B>Scanf.Scan_failure</B>
|
|
|
|
if the format string value read does not have the
|
|
same type as
|
|
<B>fmt</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.09.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val sscanf_format </I>
|
|
|
|
:
|
|
<B>string -></B>
|
|
|
|
<B>('a, 'b, 'c, 'd, 'e, 'f) format6 -></B>
|
|
|
|
<B>(('a, 'b, 'c, 'd, 'e, 'f) format6 -> 'g) -> 'g</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Scanf.bscanf_format</B>
|
|
|
|
, but reads from the given string.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.09.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val format_from_string </I>
|
|
|
|
:
|
|
<B>string -></B>
|
|
|
|
<B>('a, 'b, 'c, 'd, 'e, 'f) format6 -></B>
|
|
|
|
<B>('a, 'b, 'c, 'd, 'e, 'f) format6</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>format_from_string s fmt</B>
|
|
|
|
converts a string argument to a format string,
|
|
according to the given format string
|
|
<B>fmt</B>
|
|
|
|
.
|
|
Raise
|
|
<B>Scanf.Scan_failure</B>
|
|
|
|
if
|
|
<B>s</B>
|
|
|
|
, considered as a format string, does not
|
|
have the same type as
|
|
<B>fmt</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.10.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val unescaped </I>
|
|
|
|
:
|
|
<B>string -> string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>unescaped s</B>
|
|
|
|
return a copy of
|
|
<B>s</B>
|
|
|
|
with escape sequences (according to
|
|
the lexical conventions of OCaml) replaced by their corresponding special
|
|
characters.
|
|
More precisely,
|
|
<B>Scanf.unescaped</B>
|
|
|
|
has the following property:
|
|
for all string
|
|
<B>s</B>
|
|
|
|
,
|
|
<B>Scanf.unescaped (String.escaped s) = s</B>
|
|
|
|
.
|
|
<P>
|
|
Always return a copy of the argument, even if there is no escape sequence
|
|
in the argument.
|
|
Raise
|
|
<B>Scanf.Scan_failure</B>
|
|
|
|
if
|
|
<B>s</B>
|
|
|
|
is not properly escaped (i.e.
|
|
<B>s</B>
|
|
|
|
has invalid
|
|
escape sequences or special characters that are not properly escaped).
|
|
For instance,
|
|
<B>Scanf.unescaped \</B>
|
|
|
|
will fail.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.00.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAS"> </A>
|
|
<H3>Deprecated</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val fscanf </I>
|
|
|
|
:
|
|
<B>in_channel -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
<P>
|
|
<B>Scanf.fscanf</B>
|
|
|
|
is error prone and deprecated since 4.03.0.
|
|
<P>
|
|
This function violates the following invariant of the
|
|
<B>Scanf</B>
|
|
|
|
module:
|
|
To preserve scanning semantics, all scanning functions defined in
|
|
<B>Scanf</B>
|
|
|
|
must read from a user defined
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
formatted input
|
|
channel.
|
|
<P>
|
|
If you need to read from a
|
|
<B>in_channel</B>
|
|
|
|
input channel
|
|
<B>ic</B>
|
|
|
|
, simply define a
|
|
<B>Scanf.Scanning.in_channel</B>
|
|
|
|
formatted input channel as in
|
|
<B>let ib = Scanning.from_channel ic</B>
|
|
|
|
,
|
|
then use
|
|
<B>Scanf.bscanf ib</B>
|
|
|
|
as usual.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val kfscanf </I>
|
|
|
|
:
|
|
<B>in_channel -></B>
|
|
|
|
<B>(Scanning.in_channel -> exn -> 'd) -> ('a, 'b, 'c, 'd) scanner</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
<P>
|
|
<B>Scanf.kfscanf</B>
|
|
|
|
is error prone and deprecated since 4.03.0.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">Introduction</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">Functional input with format strings</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">A simple example</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">Formatted input as a functional feature</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">Formatted input channel</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">Type of formatted input functions</A><DD>
|
|
<DT id="10"><A HREF="#lbAK">The general formatted input function</A><DD>
|
|
<DT id="11"><A HREF="#lbAL">Format string description</A><DD>
|
|
<DT id="12"><A HREF="#lbAM">The space character in format strings</A><DD>
|
|
<DT id="13"><A HREF="#lbAN">Conversion specifications in format strings</A><DD>
|
|
<DT id="14"><A HREF="#lbAO">Scanning indications in format strings</A><DD>
|
|
<DT id="15"><A HREF="#lbAP">Exceptions during scanning</A><DD>
|
|
<DT id="16"><A HREF="#lbAQ">Specialised formatted input functions</A><DD>
|
|
<DT id="17"><A HREF="#lbAR">Reading format strings from input</A><DD>
|
|
<DT id="18"><A HREF="#lbAS">Deprecated</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:54 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|