Module Scanf

module Scanf: sig  end

Formatted input functions.

module Scanning: sig  end

Scanning buffers.

exception Scan_failure of string

The exception that formatted input functions raise when the input cannot be read according to the given format.

val bscanf : Scanning.scanbuf -> ('a, Scanning.scanbuf, 'b) format -> 'a -> 'b

bscanf ib format f reads tokens from the scanning buffer ib according to the format string format, converts these tokens to values, and applies the function f to these values. The result of this application of f is the result of the whole construct.

Raise Scanf.Scan_failure if the given input does not match the format.

Raise Failure if a conversion to a number is not possible.

Raise End_of_file if the end of input is encountered while scanning and the input matches the given format so far.

The format is a character string which contains three types of objects:

• plain characters, which are simply matched with the characters of the input,
• conversion specifications, each of which causes reading and conversion of one argument for f,
• scanning indications to specify boundaries of tokens.

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.

Conversion specifications consist in the % character, followed by optional field width, followed by one or two conversion characters. The conversion characters and their meanings are:

• d: reads an optionally signed decimal integer.
• i: reads an optionally signed integer (usual input formats for hexadecimal (0x[d]+ and 0X[d]+), octal (0o[d]+), and binary 0b[d]+ notations are understood).
• u: reads an unsigned decimal integer.
• x or X: reads an unsigned hexadecimal integer.
• o: reads an unsigned octal integer.
• s: reads a string argument (by default strings end with a space).
• S: reads a delimited string argument (delimiters and special escaped characters follow the lexical conventions of Caml).
• c: reads a single character.
• C: reads a single delimited character (delimiters and special escaped characters follow the lexical conventions of Caml).
• f, e, E, g, G: reads an optionally signed floating-point number in decimal notation, in the style dddd.ddd e/E+-dd.
• b: reads a boolean argument (true or false).
• ld, li, lu, lx, lX, lo: reads an int32 argument to the format specified by the second letter (decimal, hexadecimal, etc).
• nd, ni, nu, nx, nX, no: reads a nativeint argument to the format specified by the second letter.
• Ld, Li, Lu, Lx, LX, Lo: reads an int64 argument to the format specified by the second letter.
• [ range ]: reads characters that matches one of the characters mentioned in the range of characters range (or not mentioned in it, if the range starts with ^). Returns a string that can be empty, if no character in the input matches the range.
• N: applies f to the number of characters read so far.
• %: matches one % character in the input.

The field widths are composed of an optional integer literal indicating the maximal width of the token to read. For instance, %6d reads an integer, having at most 6 decimal digits; and %4f reads a float with 4 characters.

Scanning indications appear just after string conversions s and [ range ] to delimit the end of the token. A scanning indication is introduced by a @ character, followed by some constant character c. It means that the string token should end just before the next matching c. If no c character is encountered, the string token spreads as much as possible. For instance, "%s@\t" reads a string up to the next tabulation character. If a scanning indication @c does not follow a string conversion, it is ignored and treated as a plain c character.

Note: the scanf 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 Str), stream parsers, ocamllex-generated lexers, ocamlyacc-generated parsers.

val fscanf : Pervasives.in_channel -> ('a, Scanning.scanbuf, 'b) format -> 'a -> 'b

Same as Scanf.bscanf, but inputs from the given channel.

val sscanf : string -> ('a, Scanning.scanbuf, 'b) format -> 'a -> 'b

Same as Scanf.bscanf, but inputs from the given string.

val scanf : ('a, Scanning.scanbuf, 'b) format -> 'a -> 'b

Same as Scanf.bscanf, but inputs from stdin (the standard input channel).

val kscanf : Scanning.scanbuf ->
       (Scanning.scanbuf -> exn -> 'a) ->
       ('b, Scanning.scanbuf, 'a) format -> 'b -> 'a

Same as Scanf.bscanf, but takes an additional function argument ef 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 ef to the scanning buffer and the exception that aborted evaluation.