Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Scanf(3)			 OCaml library			      Scanf(3)

NAME
       Scanf - Formatted input functions.

Module
       Module	Scanf

Documentation
       Module Scanf
	: sig end

       Formatted input functions.

       === Introduction	===

       === Introduction	===

       === Functional input with format	strings	===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === A simple example ===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === A simple example ===

       ===  As	suggested above, the expression	bscanf ic %d f reads a decimal
       integer n from the source of characters ic and returns f	 n.   For  in-
       stance,	-  if  we  use	stdin as the source of characters (Scanf.Scan-
       ning.stdin is the predefined formatted input channel  that  reads  from
       standard	input),	- if we	define the receiver f as let f x = x + 1, then
       bscanf Scanning.stdin %d	f reads	an integer n from the  standard	 input
       and  returns  f n (that is n + 1). Thus,	if we evaluate bscanf stdin %d
       f, and then enter 41 at the keyboard, we	get 42 as  the	final  result.
       ===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === A simple example ===

       ===  As	suggested above, the expression	bscanf ic %d f reads a decimal
       integer n from the source of characters ic and returns f	 n.   For  in-
       stance,	-  if  we  use	stdin as the source of characters (Scanf.Scan-
       ning.stdin is the predefined formatted input channel  that  reads  from
       standard	input),	- if we	define the receiver f as let f x = x + 1, then
       bscanf Scanning.stdin %d	f reads	an integer n from the  standard	 input
       and  returns  f n (that is n + 1). Thus,	if we evaluate bscanf stdin %d
       f, and then enter 41 at the keyboard, we	get 42 as  the	final  result.
       ===

       === Formatted input as a	functional feature ===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === A simple example ===

       ===  As	suggested above, the expression	bscanf ic %d f reads a decimal
       integer n from the source of characters ic and returns f	 n.   For  in-
       stance,	-  if  we  use	stdin as the source of characters (Scanf.Scan-
       ning.stdin is the predefined formatted input channel  that  reads  from
       standard	input),	- if we	define the receiver f as let f x = x + 1, then
       bscanf Scanning.stdin %d	f reads	an integer n from the  standard	 input
       and  returns  f n (that is n + 1). Thus,	if we evaluate bscanf stdin %d
       f, and then enter 41 at the keyboard, we	get 42 as  the	final  result.
       ===

       === Formatted input as a	functional feature ===

       ===  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	appli-
       cation 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 in-
       put facility is fully type-checked at compile time. ===

       === Introduction	===

       === Functional input with format	strings	===

       ===  The	 module	 Scanf provides	formatted input	functions or scanners.
       The formatted input functions can read from any kind of input,  includ-
       ing  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 Scanf.Scanning.in_channel. The more gen-
       eral formatted input function reads from	any  scanning  buffer  and  is
       named bscanf.  Generally	speaking, the formatted	input functions	have 3
       arguments: - the	first argument is a source of characters for  the  in-
       put, - the second argument is a format string that specifies the	values
       to read,	- the third argument is	a receiver function that is applied to
       the values read.	 Hence,	a typical call to the formatted	input function
       Scanf.bscanf is bscanf ic fmt f,	where: - ic is a source	of  characters
       (typically  a formatted input channel with type Scanf.Scanning.in_chan-
       nel), - fmt is a	format string (the same	format strings as  those  used
       to print	material with module Printf or Format),	- f is a function that
       has as many arguments as	the number of values to	 read  in  the	input.
       ===

       === A simple example ===

       ===  As	suggested above, the expression	bscanf ic %d f reads a decimal
       integer n from the source of characters ic and returns f	 n.   For  in-
       stance,	-  if  we  use	stdin as the source of characters (Scanf.Scan-
       ning.stdin is the predefined formatted input channel  that  reads  from
       standard	input),	- if we	define the receiver f as let f x = x + 1, then
       bscanf Scanning.stdin %d	f reads	an integer n from the  standard	 input
       and  returns  f n (that is n + 1). Thus,	if we evaluate bscanf stdin %d
       f, and then enter 41 at the keyboard, we	get 42 as  the	final  result.
       ===

       === Formatted input as a	functional feature ===

       ===  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	appli-
       cation 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 in-
       put facility is fully type-checked at compile time. ===

       === Formatted input channel ===

       module Scanning : sig end

       === Type	of formatted input functions ===

       type ('a, 'b, 'c, 'd) scanner = ('a, Scanning.in_channel, 'b, 'c, 'a ->
       'd, 'd) Pervasives.format6 -> 'c

       The type	of formatted input scanners: ('a, 'b, 'c, 'd) scanner  is  the
       type of a formatted input function that reads from some formatted input
       channel according to some format	string;	more  precisely,  if  scan  is
       some  formatted input function, then scan ic fmt	f applies f to the ar-
       guments specified by the	format string fmt , when scan has  read	 those
       arguments from the formatted input channel ic .

       For  instance, the scanf	function below has type	('a, 'b, 'c, 'd) scan-
       ner , since it is a formatted input  function  that  reads  from	 Scan-
       ning.stdin  : scanf fmt f applies f to the arguments specified by fmt ,
       reading those arguments from Pervasives.stdin as	expected.

       If the format fmt has some  %r  indications,  the  corresponding	 input
       functions  must	be  provided  before  the receiver f argument. For in-
       stance, if read_elem is an input	function for values of type t  ,  then
       bscanf  ic  %r; read_elem f reads a value v of type t followed by a ';'
       character, and returns f	v .

       Since 3.10.0

       exception Scan_failure of string

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

       === The general formatted input function	===

       val bscanf : Scanning.in_channel	-> ('a,	'b, 'c,	'd) scanner

       bscanf ic fmt r1	... rN f reads arguments for the function f , from the
       formatted input channel ic , according to the format string fmt	,  and
       applies f to these values.  The result of this call to f	is returned as
       the result of the entire	bscanf call.  For instance, if f is the	 func-
       tion fun	s i -> i + 1 , then Scanf.sscanf x=  1 %s = %i f returns 2 .

       Arguments r1 to rN are user-defined input functions that	read the argu-
       ment corresponding to  the  %r  conversions  specified  in  the	format
       string.

       === Format string description ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Format string description ===

       === The format string is	a character string which contains three	 types
       of objects: - plain characters, which are simply	matched	with the char-
       acters of the input (with a special case	for space and line  feed,  see
       Scanf.space), - conversion specifications, each of which	causes reading
       and conversion of one argument for the function	f  (see	 Scanf.conver-
       sion),  -  scanning  indications	 to  specify boundaries	of tokens (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       === 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	(' ' or	 ASCII
       code  32) and the line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no amount of whitespace at all; hence, the call bscanf ib Price = %d  $
       (fun  p -> p) succeeds and returns 1 when reading an input with various
       whitespace in it, such as Price = 1 $, Price = 1	$, or  even  Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Conversion specifications consist in	the % 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:  -	d:  reads an optionally	signed decimal integer.	 - i: reads an
       optionally signed integer (usual	input conventions for decimal  (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+) notations are	understood).  -	u: reads an  unsigned  decimal
       integer.	   -   x   or	X:   reads  an	unsigned  hexadecimal  integer
       ([0-9a-fA-F]+).	- o: reads an unsigned octal integer ([0-7]+).	 -  s:
       reads  a	 string	 argument  that	spreads	as much	as possible, until the
       following bounding condition holds: - a whitespace has been found  (see
       Scanf.space),  -	 a scanning indication (see scanning Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion  always succeeds: it returns an empty	string if the bounding
       condition holds when the	scan begins.  -	S: reads  a  delimited	string
       argument	 (delimiters and special escaped characters follow the lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent  input  character  without reading it, specify a null field	width,
       i.e. use	specification %0c. Raise Invalid_argument, if the field	 width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter (delimiters and special escaped characters follow the lexical  con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F:  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).	  - B: reads a boolean argument	(true or false).  - b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).   -  ld,  li,	lu, lx,	lX, lo:	reads an int32 argument	to the
       format specified	by the second letter for regular integers.  - nd,  ni,
       nu,  nx,	 nX, no: reads a nativeint argument to the format specified by
       the second letter for regular integers.	- Ld,  Li,  Lu,	 Lx,  LX,  Lo:
       reads  an  int64	 argument to the format	specified by the second	letter
       for regular integers.  -	[ 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 ^). Reads a string  that  can
       be empty, if the	next input character does not match the	range. The set
       of characters from c1 to	c2 (inclusively) is denoted by c1-c2.	Hence,
       %[0-9]  returns	a  string  representing	 a  decimal number or an empty
       string if no decimal digit is found;  similarly,	 %[0-9a-f]  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  ^
       in  case	 of  range negation); hence []]	matches	a ] character and [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @  in  a	 range.	 - r: user-defined reader. Takes the next ri formatted
       input function and applies it to	the scanning buffer  ib	 to  read  the
       next  argument.	The  input  function ri	must therefore have type Scan-
       ning.in_channel -> 'a and the argument read has type 'a.	 - {  fmt  %}:
       reads  a	 format	 string	argument. The format string read must have the
       same type as the	format string specification fmt. For instance,	%{  %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s is the	string fmt:\ number is %u\"", then Scanf.sscanf	s fmt:	%{%i%}
       succeeds	 and  returns  the  format  string number is %u	.  - ( fmt %):
       scanning	sub-format substitution.  Reads	a format string	rf in the  in-
       put,  then  goes	on scanning with rf instead of scanning	with fmt.  The
       format string rf	must have the same type	as the format string  specifi-
       cation  fmt  that it replaces.  For instance, %(	%i %) reads any	format
       string that can read a value of type int.  The conversion  returns  the
       format  string read rf, and then	a value	read using rf.	Hence, if s is
       the string \ %4d\"1234.00", then	Scanf.sscanf s %(%i%) (fun  fmt	 i  ->
       fmt,  i)	evaluates to ("%4d", 1234).  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 _ to discard the extraneous	argument: conversion %_( fmt %)	 reads
       a  format  string  rf  and  then	 behaves the same as format string rf.
       Hence, if s is the string \ %4d\"1234.00", then Scanf.sscanf s  %_(%i%)
       is  simply  equivalent  to Scanf.sscanf 1234.00 %4d .  -	l: returns the
       number of lines read so far.  - n: returns  the	number	of  characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches the end of input	condition.  - %: matches one  %	 character  in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the resulting value is discarded.  For instance,	if f is	 the  function
       fun  i  -> i + 1, and s is the string x = 1 , then Scanf.sscanf s %_s =
       %i f returns 2.	The field width	is composed  of	 an  optional  integer
       literal	indicating  the	 maximal  width	of the token to	read.  For in-
       stance, %6d reads an integer, having at	most  6	 decimal  digits;  %4f
       reads  a	float with at most 4 characters; and %8[\000-\255] returns the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a %s conversion always succeeds,	even if	there is nothing  to  read  in
       the  input:  in	this  case, it simply returns  .  - in addition	to the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	 to the	usual OCaml lexical conventions). If stricter scanning
       is desired, use the range conversion facility  instead  of  the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal 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.
       ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Conversion specifications consist in	the % 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:  -	d:  reads an optionally	signed decimal integer.	 - i: reads an
       optionally signed integer (usual	input conventions for decimal  (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+) notations are	understood).  -	u: reads an  unsigned  decimal
       integer.	   -   x   or	X:   reads  an	unsigned  hexadecimal  integer
       ([0-9a-fA-F]+).	- o: reads an unsigned octal integer ([0-7]+).	 -  s:
       reads  a	 string	 argument  that	spreads	as much	as possible, until the
       following bounding condition holds: - a whitespace has been found  (see
       Scanf.space),  -	 a scanning indication (see scanning Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion  always succeeds: it returns an empty	string if the bounding
       condition holds when the	scan begins.  -	S: reads  a  delimited	string
       argument	 (delimiters and special escaped characters follow the lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent  input  character  without reading it, specify a null field	width,
       i.e. use	specification %0c. Raise Invalid_argument, if the field	 width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter (delimiters and special escaped characters follow the lexical  con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F:  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).	  - B: reads a boolean argument	(true or false).  - b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).   -  ld,  li,	lu, lx,	lX, lo:	reads an int32 argument	to the
       format specified	by the second letter for regular integers.  - nd,  ni,
       nu,  nx,	 nX, no: reads a nativeint argument to the format specified by
       the second letter for regular integers.	- Ld,  Li,  Lu,	 Lx,  LX,  Lo:
       reads  an  int64	 argument to the format	specified by the second	letter
       for regular integers.  -	[ 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 ^). Reads a string  that  can
       be empty, if the	next input character does not match the	range. The set
       of characters from c1 to	c2 (inclusively) is denoted by c1-c2.	Hence,
       %[0-9]  returns	a  string  representing	 a  decimal number or an empty
       string if no decimal digit is found;  similarly,	 %[0-9a-f]  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  ^
       in  case	 of  range negation); hence []]	matches	a ] character and [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @  in  a	 range.	 - r: user-defined reader. Takes the next ri formatted
       input function and applies it to	the scanning buffer  ib	 to  read  the
       next  argument.	The  input  function ri	must therefore have type Scan-
       ning.in_channel -> 'a and the argument read has type 'a.	 - {  fmt  %}:
       reads  a	 format	 string	argument. The format string read must have the
       same type as the	format string specification fmt. For instance,	%{  %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s is the	string fmt:\ number is %u\"", then Scanf.sscanf	s fmt:	%{%i%}
       succeeds	 and  returns  the  format  string number is %u	.  - ( fmt %):
       scanning	sub-format substitution.  Reads	a format string	rf in the  in-
       put,  then  goes	on scanning with rf instead of scanning	with fmt.  The
       format string rf	must have the same type	as the format string  specifi-
       cation  fmt  that it replaces.  For instance, %(	%i %) reads any	format
       string that can read a value of type int.  The conversion  returns  the
       format  string read rf, and then	a value	read using rf.	Hence, if s is
       the string \ %4d\"1234.00", then	Scanf.sscanf s %(%i%) (fun  fmt	 i  ->
       fmt,  i)	evaluates to ("%4d", 1234).  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 _ to discard the extraneous	argument: conversion %_( fmt %)	 reads
       a  format  string  rf  and  then	 behaves the same as format string rf.
       Hence, if s is the string \ %4d\"1234.00", then Scanf.sscanf s  %_(%i%)
       is  simply  equivalent  to Scanf.sscanf 1234.00 %4d .  -	l: returns the
       number of lines read so far.  - n: returns  the	number	of  characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches the end of input	condition.  - %: matches one  %	 character  in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the resulting value is discarded.  For instance,	if f is	 the  function
       fun  i  -> i + 1, and s is the string x = 1 , then Scanf.sscanf s %_s =
       %i f returns 2.	The field width	is composed  of	 an  optional  integer
       literal	indicating  the	 maximal  width	of the token to	read.  For in-
       stance, %6d reads an integer, having at	most  6	 decimal  digits;  %4f
       reads  a	float with at most 4 characters; and %8[\000-\255] returns the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a %s conversion always succeeds,	even if	there is nothing  to  read  in
       the  input:  in	this  case, it simply returns  .  - in addition	to the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	 to the	usual OCaml lexical conventions). If stricter scanning
       is desired, use the range conversion facility  instead  of  the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal 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.
       ===

       === Scanning indications	in format strings ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Conversion specifications consist in	the % 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:  -	d:  reads an optionally	signed decimal integer.	 - i: reads an
       optionally signed integer (usual	input conventions for decimal  (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+) notations are	understood).  -	u: reads an  unsigned  decimal
       integer.	   -   x   or	X:   reads  an	unsigned  hexadecimal  integer
       ([0-9a-fA-F]+).	- o: reads an unsigned octal integer ([0-7]+).	 -  s:
       reads  a	 string	 argument  that	spreads	as much	as possible, until the
       following bounding condition holds: - a whitespace has been found  (see
       Scanf.space),  -	 a scanning indication (see scanning Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion  always succeeds: it returns an empty	string if the bounding
       condition holds when the	scan begins.  -	S: reads  a  delimited	string
       argument	 (delimiters and special escaped characters follow the lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent  input  character  without reading it, specify a null field	width,
       i.e. use	specification %0c. Raise Invalid_argument, if the field	 width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter (delimiters and special escaped characters follow the lexical  con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F:  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).	  - B: reads a boolean argument	(true or false).  - b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).   -  ld,  li,	lu, lx,	lX, lo:	reads an int32 argument	to the
       format specified	by the second letter for regular integers.  - nd,  ni,
       nu,  nx,	 nX, no: reads a nativeint argument to the format specified by
       the second letter for regular integers.	- Ld,  Li,  Lu,	 Lx,  LX,  Lo:
       reads  an  int64	 argument to the format	specified by the second	letter
       for regular integers.  -	[ 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 ^). Reads a string  that  can
       be empty, if the	next input character does not match the	range. The set
       of characters from c1 to	c2 (inclusively) is denoted by c1-c2.	Hence,
       %[0-9]  returns	a  string  representing	 a  decimal number or an empty
       string if no decimal digit is found;  similarly,	 %[0-9a-f]  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  ^
       in  case	 of  range negation); hence []]	matches	a ] character and [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @  in  a	 range.	 - r: user-defined reader. Takes the next ri formatted
       input function and applies it to	the scanning buffer  ib	 to  read  the
       next  argument.	The  input  function ri	must therefore have type Scan-
       ning.in_channel -> 'a and the argument read has type 'a.	 - {  fmt  %}:
       reads  a	 format	 string	argument. The format string read must have the
       same type as the	format string specification fmt. For instance,	%{  %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s is the	string fmt:\ number is %u\"", then Scanf.sscanf	s fmt:	%{%i%}
       succeeds	 and  returns  the  format  string number is %u	.  - ( fmt %):
       scanning	sub-format substitution.  Reads	a format string	rf in the  in-
       put,  then  goes	on scanning with rf instead of scanning	with fmt.  The
       format string rf	must have the same type	as the format string  specifi-
       cation  fmt  that it replaces.  For instance, %(	%i %) reads any	format
       string that can read a value of type int.  The conversion  returns  the
       format  string read rf, and then	a value	read using rf.	Hence, if s is
       the string \ %4d\"1234.00", then	Scanf.sscanf s %(%i%) (fun  fmt	 i  ->
       fmt,  i)	evaluates to ("%4d", 1234).  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 _ to discard the extraneous	argument: conversion %_( fmt %)	 reads
       a  format  string  rf  and  then	 behaves the same as format string rf.
       Hence, if s is the string \ %4d\"1234.00", then Scanf.sscanf s  %_(%i%)
       is  simply  equivalent  to Scanf.sscanf 1234.00 %4d .  -	l: returns the
       number of lines read so far.  - n: returns  the	number	of  characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches the end of input	condition.  - %: matches one  %	 character  in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the resulting value is discarded.  For instance,	if f is	 the  function
       fun  i  -> i + 1, and s is the string x = 1 , then Scanf.sscanf s %_s =
       %i f returns 2.	The field width	is composed  of	 an  optional  integer
       literal	indicating  the	 maximal  width	of the token to	read.  For in-
       stance, %6d reads an integer, having at	most  6	 decimal  digits;  %4f
       reads  a	float with at most 4 characters; and %8[\000-\255] returns the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a %s conversion always succeeds,	even if	there is nothing  to  read  in
       the  input:  in	this  case, it simply returns  .  - in addition	to the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	 to the	usual OCaml lexical conventions). If stricter scanning
       is desired, use the range conversion facility  instead  of  the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal 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.
       ===

       === Scanning indications	in format strings ===

       ===  Scanning  indications  appear just after the string	conversions %s
       and %[ range ] to delimit the end of the	token. A  scanning  indication
       is  introduced by a @ character,	followed by some plain character c. It
       means that the string token should end just before the next matching  c
       (which  is skipped). 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	tab character or to the	end of input. If a @ character appears
       anywhere	else in	the format string, it is treated as a plain character.
       Note:  -	As usual in format strings, % and @ characters must be escaped
       using %%	and %@;	this rule still	holds within range specifications  and
       scanning	 indications.	For  instance,	%s@%% reads a string up	to the
       next % character.  - The	scanning indications introduce slight  differ-
       ences in	the syntax of Scanf format strings, compared to	those used for
       the Printf module. However, the scanning	 indications  are  similar  to
       those  used  in the Format module; hence, when producing	formatted text
       to be scanned by	!Scanf.bscanf, it is wise to  use  printing  functions
       from  the  Format module	(or, if	you need to use	functions from Printf,
       banish or carefully double check	the format strings  that  contain  '@'
       characters).  ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Conversion specifications consist in	the % 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:  -	d:  reads an optionally	signed decimal integer.	 - i: reads an
       optionally signed integer (usual	input conventions for decimal  (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+) notations are	understood).  -	u: reads an  unsigned  decimal
       integer.	   -   x   or	X:   reads  an	unsigned  hexadecimal  integer
       ([0-9a-fA-F]+).	- o: reads an unsigned octal integer ([0-7]+).	 -  s:
       reads  a	 string	 argument  that	spreads	as much	as possible, until the
       following bounding condition holds: - a whitespace has been found  (see
       Scanf.space),  -	 a scanning indication (see scanning Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion  always succeeds: it returns an empty	string if the bounding
       condition holds when the	scan begins.  -	S: reads  a  delimited	string
       argument	 (delimiters and special escaped characters follow the lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent  input  character  without reading it, specify a null field	width,
       i.e. use	specification %0c. Raise Invalid_argument, if the field	 width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter (delimiters and special escaped characters follow the lexical  con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F:  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).	  - B: reads a boolean argument	(true or false).  - b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).   -  ld,  li,	lu, lx,	lX, lo:	reads an int32 argument	to the
       format specified	by the second letter for regular integers.  - nd,  ni,
       nu,  nx,	 nX, no: reads a nativeint argument to the format specified by
       the second letter for regular integers.	- Ld,  Li,  Lu,	 Lx,  LX,  Lo:
       reads  an  int64	 argument to the format	specified by the second	letter
       for regular integers.  -	[ 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 ^). Reads a string  that  can
       be empty, if the	next input character does not match the	range. The set
       of characters from c1 to	c2 (inclusively) is denoted by c1-c2.	Hence,
       %[0-9]  returns	a  string  representing	 a  decimal number or an empty
       string if no decimal digit is found;  similarly,	 %[0-9a-f]  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  ^
       in  case	 of  range negation); hence []]	matches	a ] character and [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @  in  a	 range.	 - r: user-defined reader. Takes the next ri formatted
       input function and applies it to	the scanning buffer  ib	 to  read  the
       next  argument.	The  input  function ri	must therefore have type Scan-
       ning.in_channel -> 'a and the argument read has type 'a.	 - {  fmt  %}:
       reads  a	 format	 string	argument. The format string read must have the
       same type as the	format string specification fmt. For instance,	%{  %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s is the	string fmt:\ number is %u\"", then Scanf.sscanf	s fmt:	%{%i%}
       succeeds	 and  returns  the  format  string number is %u	.  - ( fmt %):
       scanning	sub-format substitution.  Reads	a format string	rf in the  in-
       put,  then  goes	on scanning with rf instead of scanning	with fmt.  The
       format string rf	must have the same type	as the format string  specifi-
       cation  fmt  that it replaces.  For instance, %(	%i %) reads any	format
       string that can read a value of type int.  The conversion  returns  the
       format  string read rf, and then	a value	read using rf.	Hence, if s is
       the string \ %4d\"1234.00", then	Scanf.sscanf s %(%i%) (fun  fmt	 i  ->
       fmt,  i)	evaluates to ("%4d", 1234).  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 _ to discard the extraneous	argument: conversion %_( fmt %)	 reads
       a  format  string  rf  and  then	 behaves the same as format string rf.
       Hence, if s is the string \ %4d\"1234.00", then Scanf.sscanf s  %_(%i%)
       is  simply  equivalent  to Scanf.sscanf 1234.00 %4d .  -	l: returns the
       number of lines read so far.  - n: returns  the	number	of  characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches the end of input	condition.  - %: matches one  %	 character  in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the resulting value is discarded.  For instance,	if f is	 the  function
       fun  i  -> i + 1, and s is the string x = 1 , then Scanf.sscanf s %_s =
       %i f returns 2.	The field width	is composed  of	 an  optional  integer
       literal	indicating  the	 maximal  width	of the token to	read.  For in-
       stance, %6d reads an integer, having at	most  6	 decimal  digits;  %4f
       reads  a	float with at most 4 characters; and %8[\000-\255] returns the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a %s conversion always succeeds,	even if	there is nothing  to  read  in
       the  input:  in	this  case, it simply returns  .  - in addition	to the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	 to the	usual OCaml lexical conventions). If stricter scanning
       is desired, use the range conversion facility  instead  of  the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal 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.
       ===

       === Scanning indications	in format strings ===

       ===  Scanning  indications  appear just after the string	conversions %s
       and %[ range ] to delimit the end of the	token. A  scanning  indication
       is  introduced by a @ character,	followed by some plain character c. It
       means that the string token should end just before the next matching  c
       (which  is skipped). 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	tab character or to the	end of input. If a @ character appears
       anywhere	else in	the format string, it is treated as a plain character.
       Note:  -	As usual in format strings, % and @ characters must be escaped
       using %%	and %@;	this rule still	holds within range specifications  and
       scanning	 indications.	For  instance,	%s@%% reads a string up	to the
       next % character.  - The	scanning indications introduce slight  differ-
       ences in	the syntax of Scanf format strings, compared to	those used for
       the Printf module. However, the scanning	 indications  are  similar  to
       those  used  in the Format module; hence, when producing	formatted text
       to be scanned by	!Scanf.bscanf, it is wise to  use  printing  functions
       from  the  Format module	(or, if	you need to use	functions from Printf,
       banish or carefully double check	the format strings  that  contain  '@'
       characters).  ===

       === Exceptions during scanning ===

       === Format string description ===

       ===  The	format string is a character string which contains three types
       of objects: - plain characters, which are simply	matched	with the char-
       acters  of  the input (with a special case for space and	line feed, see
       Scanf.space), - conversion specifications, each of which	causes reading
       and  conversion	of  one	argument for the function f (see Scanf.conver-
       sion), -	scanning indications to	 specify  boundaries  of  tokens  (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       ===  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 (' ' or ASCII
       code 32)	and the	line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no  amount of whitespace	at all;	hence, the call	bscanf ib Price	= %d $
       (fun p -> p) succeeds and returns 1 when	reading	an input with  various
       whitespace  in  it, such	as Price = 1 $,	Price =	1 $, or	even Price=1$.
       ===

       === Conversion specifications in	format strings ===

       === Conversion specifications consist in	the % 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:  -	d:  reads an optionally	signed decimal integer.	 - i: reads an
       optionally signed integer (usual	input conventions for decimal  (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+) notations are	understood).  -	u: reads an  unsigned  decimal
       integer.	   -   x   or	X:   reads  an	unsigned  hexadecimal  integer
       ([0-9a-fA-F]+).	- o: reads an unsigned octal integer ([0-7]+).	 -  s:
       reads  a	 string	 argument  that	spreads	as much	as possible, until the
       following bounding condition holds: - a whitespace has been found  (see
       Scanf.space),  -	 a scanning indication (see scanning Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion  always succeeds: it returns an empty	string if the bounding
       condition holds when the	scan begins.  -	S: reads  a  delimited	string
       argument	 (delimiters and special escaped characters follow the lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent  input  character  without reading it, specify a null field	width,
       i.e. use	specification %0c. Raise Invalid_argument, if the field	 width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter (delimiters and special escaped characters follow the lexical  con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F:  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).	  - B: reads a boolean argument	(true or false).  - b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).   -  ld,  li,	lu, lx,	lX, lo:	reads an int32 argument	to the
       format specified	by the second letter for regular integers.  - nd,  ni,
       nu,  nx,	 nX, no: reads a nativeint argument to the format specified by
       the second letter for regular integers.	- Ld,  Li,  Lu,	 Lx,  LX,  Lo:
       reads  an  int64	 argument to the format	specified by the second	letter
       for regular integers.  -	[ 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 ^). Reads a string  that  can
       be empty, if the	next input character does not match the	range. The set
       of characters from c1 to	c2 (inclusively) is denoted by c1-c2.	Hence,
       %[0-9]  returns	a  string  representing	 a  decimal number or an empty
       string if no decimal digit is found;  similarly,	 %[0-9a-f]  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  ^
       in  case	 of  range negation); hence []]	matches	a ] character and [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @  in  a	 range.	 - r: user-defined reader. Takes the next ri formatted
       input function and applies it to	the scanning buffer  ib	 to  read  the
       next  argument.	The  input  function ri	must therefore have type Scan-
       ning.in_channel -> 'a and the argument read has type 'a.	 - {  fmt  %}:
       reads  a	 format	 string	argument. The format string read must have the
       same type as the	format string specification fmt. For instance,	%{  %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s is the	string fmt:\ number is %u\"", then Scanf.sscanf	s fmt:	%{%i%}
       succeeds	 and  returns  the  format  string number is %u	.  - ( fmt %):
       scanning	sub-format substitution.  Reads	a format string	rf in the  in-
       put,  then  goes	on scanning with rf instead of scanning	with fmt.  The
       format string rf	must have the same type	as the format string  specifi-
       cation  fmt  that it replaces.  For instance, %(	%i %) reads any	format
       string that can read a value of type int.  The conversion  returns  the
       format  string read rf, and then	a value	read using rf.	Hence, if s is
       the string \ %4d\"1234.00", then	Scanf.sscanf s %(%i%) (fun  fmt	 i  ->
       fmt,  i)	evaluates to ("%4d", 1234).  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 _ to discard the extraneous	argument: conversion %_( fmt %)	 reads
       a  format  string  rf  and  then	 behaves the same as format string rf.
       Hence, if s is the string \ %4d\"1234.00", then Scanf.sscanf s  %_(%i%)
       is  simply  equivalent  to Scanf.sscanf 1234.00 %4d .  -	l: returns the
       number of lines read so far.  - n: returns  the	number	of  characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches the end of input	condition.  - %: matches one  %	 character  in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the resulting value is discarded.  For instance,	if f is	 the  function
       fun  i  -> i + 1, and s is the string x = 1 , then Scanf.sscanf s %_s =
       %i f returns 2.	The field width	is composed  of	 an  optional  integer
       literal	indicating  the	 maximal  width	of the token to	read.  For in-
       stance, %6d reads an integer, having at	most  6	 decimal  digits;  %4f
       reads  a	float with at most 4 characters; and %8[\000-\255] returns the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a %s conversion always succeeds,	even if	there is nothing  to  read  in
       the  input:  in	this  case, it simply returns  .  - in addition	to the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	 to the	usual OCaml lexical conventions). If stricter scanning
       is desired, use the range conversion facility  instead  of  the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal 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.
       ===

       === Scanning indications	in format strings ===

       ===  Scanning  indications  appear just after the string	conversions %s
       and %[ range ] to delimit the end of the	token. A  scanning  indication
       is  introduced by a @ character,	followed by some plain character c. It
       means that the string token should end just before the next matching  c
       (which  is skipped). 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	tab character or to the	end of input. If a @ character appears
       anywhere	else in	the format string, it is treated as a plain character.
       Note:  -	As usual in format strings, % and @ characters must be escaped
       using %%	and %@;	this rule still	holds within range specifications  and
       scanning	 indications.	For  instance,	%s@%% reads a string up	to the
       next % character.  - The	scanning indications introduce slight  differ-
       ences in	the syntax of Scanf format strings, compared to	those used for
       the Printf module. However, the scanning	 indications  are  similar  to
       those  used  in the Format module; hence, when producing	formatted text
       to be scanned by	!Scanf.bscanf, it is wise to  use  printing  functions
       from  the  Format module	(or, if	you need to use	functions from Printf,
       banish or carefully double check	the format strings  that  contain  '@'
       characters).  ===

       === Exceptions during scanning ===

       ===  Scanners  may raise	the following exceptions when the input	cannot
       be read according to the	format string: - Raise	Scanf.Scan_failure  if
       the  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 some more	characters are needed to read the cur-
       rent conversion specification.  - Raise Invalid_argument	if the	format
       string  is invalid.  Note: - as a consequence, scanning a %s conversion
       never raises exception End_of_file: if the end of input is reached  the
       conversion  succeeds  and simply	returns	the characters read so far, or
       if none were ever read.	===

       === Format string description ===

       === The format string is	a character string which contains three	 types
       of objects: - plain characters, which are simply	matched	with the char-
       acters of the input (with a special case	for space and line  feed,  see
       Scanf.space), - conversion specifications, each of which	causes reading
       and conversion of one argument for the function	f  (see	 Scanf.conver-
       sion),  -  scanning  indications	 to  specify boundaries	of tokens (see
       scanning	Scanf.indication).  ===

       === The space character in format strings ===

       === 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	(' ' or	 ASCII
       code  32) and the line feed character ('\n' 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.	Match-
       ing any amount of whitespace, a space in	the format string also matches
       no amount of whitespace at all; hence, the call bscanf ib Price = %d  $
       (fun  p -> p) succeeds and returns 1 when reading an input with various
       whitespace in it, such as Price = 1 $, Price = 1	$, or  even  Price=1$.
       ===

       === Conversion specifications in	format strings ===

       ===  Conversion	specifications consist in the %	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: - d: reads an optionally signed decimal integer.  -	 i:  reads  an
       optionally  signed integer (usual input conventions for decimal (0-9+),
       hexadecimal (0x[0-9a-f]+	and 0X[0-9A-F]+), octal	(0o[0-7]+), and	binary
       (0b[0-1]+)  notations  are understood).	- u: reads an unsigned decimal
       integer.	  -  x	or  X:	 reads	 an   unsigned	 hexadecimal   integer
       ([0-9a-fA-F]+).	 -  o: reads an	unsigned octal integer ([0-7]+).  - s:
       reads a string argument that spreads as much  as	 possible,  until  the
       following  bounding condition holds: - a	whitespace has been found (see
       Scanf.space), - a scanning indication (see  scanning  Scanf.indication)
       has been	encountered, - the end-of-input	has been reached.  Hence, this
       conversion always succeeds: it returns an empty string if the  bounding
       condition  holds	 when  the scan	begins.	 - S: reads a delimited	string
       argument	(delimiters and	special	escaped	characters follow the  lexical
       conventions of OCaml).  - c: reads a single character. To test the cur-
       rent input character without reading it,	specify	a  null	 field	width,
       i.e.  use specification %0c. Raise Invalid_argument, if the field width
       specification is	greater	than 1.	 - C: reads a single delimited charac-
       ter  (delimiters	and special escaped characters follow the lexical con-
       ventions	of OCaml).  - f, e, E, g, G: reads an optionally signed	float-
       ing-point number	in decimal notation, in	the style dddd.ddd e/E+-dd.  -
       F: 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).	- B: reads a boolean argument (true or false).	 -  b:
       reads a boolean argument	(for backward compatibility; do	not use	in new
       programs).  - ld, li, lu, lx, lX, lo: reads an int32  argument  to  the
       format  specified by the	second letter for regular integers.  - nd, ni,
       nu, nx, nX, no: reads a nativeint argument to the format	 specified  by
       the  second  letter  for	 regular  integers.  - Ld, Li, Lu, Lx, LX, Lo:
       reads an	int64 argument to the format specified by  the	second	letter
       for  regular  integers.	- [ 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 ^). Reads a string that can
       be empty, if the	next input character does not match the	range. The set
       of  characters from c1 to c2 (inclusively) is denoted by	c1-c2.	Hence,
       %[0-9] returns a	string representing  a	decimal	 number	 or  an	 empty
       string  if  no  decimal	digit is found;	similarly, %[0-9a-f] 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 ^
       in case of range	negation); hence []] matches a ]  character  and  [^]]
       matches any character that is not ].  Use %% and	%@ to include a	% or a
       @ in a range.  -	r: user-defined	reader.	Takes the  next	 ri  formatted
       input  function	and  applies  it to the	scanning buffer	ib to read the
       next argument. The input	function ri must  therefore  have  type	 Scan-
       ning.in_channel	->  'a and the argument	read has type 'a.  - { fmt %}:
       reads a format string argument. The format string read  must  have  the
       same  type  as the format string	specification fmt. For instance, %{ %i
       %} reads	any format string that can read	a value	of type	int; hence, if
       s  is the string	fmt:\ number is	%u\"", then Scanf.sscanf s fmt:	%{%i%}
       succeeds	and returns the	format string number is	%u  .	-  (  fmt  %):
       scanning	 sub-format substitution.  Reads a format string rf in the in-
       put, then goes on scanning with rf instead of scanning with  fmt.   The
       format  string rf must have the same type as the	format string specifi-
       cation fmt that it replaces.  For instance, %( %i %) reads  any	format
       string  that  can read a	value of type int.  The	conversion returns the
       format string read rf, and then a value read using rf.  Hence, if s  is
       the  string  \  %4d\"1234.00", then Scanf.sscanf	s %(%i%) (fun fmt i ->
       fmt, i) evaluates to ("%4d", 1234).  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  _ to discard the extraneous argument: conversion %_( fmt %) reads
       a format	string rf and then behaves  the	 same  as  format  string  rf.
       Hence,  if s is the string \ %4d\"1234.00", then	Scanf.sscanf s %_(%i%)
       is simply equivalent to Scanf.sscanf 1234.00 %4d	.  -  l:  returns  the
       number  of  lines  read	so far.	 - n: returns the number of characters
       read so far.  - N or L: returns the number of tokens read so far.  - !:
       matches	the  end  of input condition.  - %: matches one	% character in
       the input.  - @:	matches	one @ character	in the input.  - ,: does noth-
       ing.  Following the % character that introduces a conversion, there may
       be the special flag _: the conversion that follows occurs as usual, but
       the  resulting  value is	discarded.  For	instance, if f is the function
       fun i ->	i + 1, and s is	the string x = 1 , then	Scanf.sscanf s	%_s  =
       %i  f  returns  2.   The	field width is composed	of an optional integer
       literal indicating the maximal width of the token  to  read.   For  in-
       stance,	%6d  reads  an	integer,  having at most 6 decimal digits; %4f
       reads a float with at most 4 characters;	and %8[\000-\255] returns  the
       next 8 characters (or all the characters	still available, if fewer than
       8 characters are	available in the input).  Notes: - as mentioned	above,
       a  %s  conversion  always succeeds, even	if there is nothing to read in
       the input: in this case,	it simply returns  .  -	 in  addition  to  the
       relevant	digits,	'_' characters may appear inside numbers (this is rem-
       iniscent	to the usual OCaml lexical conventions). If stricter  scanning
       is  desired,  use  the  range conversion	facility instead of the	number
       conversions.  - the scanf facility is not intended for heavy duty lexi-
       cal  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.
       ===

       === Scanning indications	in format strings ===

       === Scanning indications	appear just after the  string  conversions  %s
       and  %[	range ]	to delimit the end of the token. A scanning indication
       is introduced by	a @ character, followed	by some	plain character	c.  It
       means  that the string token should end just before the next matching c
       (which is skipped). 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	tab character or to the	end of input. If a @ character appears
       anywhere	else in	the format string, it is treated as a plain character.
       Note: - As usual	in format strings, % and @ characters must be  escaped
       using  %% and %@; this rule still holds within range specifications and
       scanning	indications.  For instance, %s@%% reads	a  string  up  to  the
       next  % character.  - The scanning indications introduce	slight differ-
       ences in	the syntax of Scanf format strings, compared to	those used for
       the  Printf  module.  However,  the scanning indications	are similar to
       those used in the Format	module;	hence, when producing  formatted  text
       to  be  scanned	by !Scanf.bscanf, it is	wise to	use printing functions
       from the	Format module (or, if you need to use functions	 from  Printf,
       banish  or  carefully  double check the format strings that contain '@'
       characters).  ===

       === Exceptions during scanning ===

       === Scanners may	raise the following exceptions when the	 input	cannot
       be  read	 according to the format string: - Raise Scanf.Scan_failure if
       the 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 some more characters are needed to read  the  cur-
       rent  conversion	specification.	- Raise	Invalid_argument if the	format
       string is invalid.  Note: - as a	consequence, scanning a	%s  conversion
       never  raises exception End_of_file: if the end of input	is reached the
       conversion succeeds and simply returns the characters read so  far,  or
       if none were ever read.	===

       === Specialised formatted input functions ===

       val fscanf : Pervasives.in_channel -> ('a, 'b, 'c, 'd) scanner

       Same as Scanf.bscanf , but reads	from the given regular input channel.

       Warning:	 since	all formatted input functions operate from a formatted
       input channel, be aware that each fscanf	invocation will	operate	with a
       formatted  input	 channel  reading  from	 the given channel. This extra
       level of	bufferization can lead to a strange scanning behaviour if  you
       use  low	 level	primitives on the channel (reading characters, seeking
       the reading position, and so on).

       As a consequence, never mix direct low level  reading  and  high	 level
       scanning	from the same regular input channel.

       val sscanf : string -> ('a, 'b, 'c, 'd) scanner

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

       val scanf : ('a,	'b, 'c,	'd) scanner

       Same  as	 Scanf.bscanf  , but reads from	the predefined formatted input
       channel Scanf.Scanning.stdin that is connected to Pervasives.stdin .

       val kscanf : Scanning.in_channel	-> (Scanning.in_channel	-> exn ->  'd)
       -> ('a, 'b, 'c, 'd) scanner

       Same  as	 Scanf.bscanf  ,  but takes an additional function argument ef
       that is called in case of error:	if the scanning	process	or  some  con-
       version	fails,	the  scanning function aborts and calls	the error han-
       dling function ef with the formatted input channel  and	the  exception
       that aborted the	scanning process as arguments.

       val  ksscanf : string ->	(Scanning.in_channel ->	exn -> 'd) -> ('a, 'b,
       'c, 'd) scanner

       Same as Scanf.kscanf but	reads from the given string.

       Since 4.02.0

       val kfscanf : Pervasives.in_channel -> (Scanning.in_channel ->  exn  ->
       'd) -> ('a, 'b, 'c, 'd) scanner

       Same as Scanf.kscanf , but reads	from the given regular input channel.

       Since 4.02.0

       === Reading format strings from input ===

       val  bscanf_format  :  Scanning.in_channel  -> ('a, 'b, 'c, 'd, 'e, 'f)
       Pervasives.format6 -> (('a, 'b, 'c, 'd, 'e, 'f)	Pervasives.format6  ->
       'g) -> 'g

       bscanf_format  ic  fmt f	reads a	format string token from the formatted
       input channel ic	, according to the given format	string fmt ,  and  ap-
       plies  f	 to  the resulting format string value.	 Raise Scan_failure if
       the format string value read does not have the same type	as fmt .

       Since 3.09.0

       val sscanf_format : string -> ('a, 'b, 'c, 'd, 'e, 'f)  Pervasives.for-
       mat6 -> (('a, 'b, 'c, 'd, 'e, 'f) Pervasives.format6 -> 'g) -> 'g

       Same as Scanf.bscanf_format , but reads from the	given string.

       Since 3.09.0

       val  format_from_string	:  string  ->  ('a, 'b,	'c, 'd,	'e, 'f)	Perva-
       sives.format6 ->	('a, 'b, 'c, 'd, 'e, 'f) Pervasives.format6

       format_from_string s fmt	converts a string argument to a	format string,
       according  to  the given	format string fmt .  Raise Scan_failure	if s ,
       considered as a format string, does not have the	same type as fmt .

       Since 3.10.0

       val unescaped : string -> string

       Return a	copy of	the argument with escape sequences, following the lex-
       ical  conventions  of  OCaml,  replaced	by their corresponding special
       characters. If there is no escape sequence in the argument,  still  re-
       turn a copy, contrary to	String.escaped.

       Since 4.00.0

OCamldoc			  2017-04-30			      Scanf(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Scanf&sektion=3o&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help