# 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.