-------------------------------------
This file has been translated from LaTeX by HeVeA.

16.1  Module Pervasives: the initially opened module
====================================================

   Pervasives (module)@`Pervasives' (module)
                This module provides the built-in types (numbers, booleans,
               strings, exceptions, references, lists, arrays, input-output
               channels, ...) and the basic operations over these types.This
               module is automatically opened at the beginning of each
               compilation. All components of this module can therefore be
               referred by their short name, without prefixing them by
               `Pervasives'.

Predefined types
=-=-=-=-=-=-=-=-=

<<
  type int
>>

                The type of integer numbers.

<<
  type char
>>

                The type of characters.

<<
  type string
>>

                The type of character strings.

<<
  type float
>>

                The type of floating-point numbers.

<<
  type bool
>>

                The type of booleans (truth values).

<<
  type unit = ()
>>

                The type of the unit value.

<<
  type exn
>>

                The type of exception values.

<<
  type 'a array
>>

                The type of arrays whose elements have type `'a'.

<<
  type 'a list = [] | :: of 'a * 'a list
>>

                The type of lists whose elements have type `'a'.

<<
  type 'a option = None | Some of 'a
>>

                The type of optional values.

<<
  type ('a, 'b, 'c) format
>>

                The type of format strings. `'a' is the type of the parameters
               of the format, `'c' is the result type for the `printf'-style
               function, and `'b' is the type of the first argument given to
               `%a' and `%t' printing functions (see module `Printf').

Exceptions
=-=-=-=-=-=

<<
  val raise : exn -> 'a
>>
   raise@`raise'
                Raise the given exception value

<<
  exception Match_failure of (string * int * int)
>>
   Match_failure (exception)@`Match_failure' (exception)
                Exception raised when none of the cases of a pattern-matching
               apply. The arguments are the location of the pattern-matching in
               the source code (file name, position of first character,
               position of last character).

<<
  exception Assert_failure of (string * int * int)
>>
   Assert_failure (exception)@`Assert_failure' (exception)
                Exception raised when an assertion fails. The arguments are the
               location of the pattern-matching in the source code (file name,
               position of first character, position of last character).

<<
  exception Invalid_argument of string
>>
   Invalid_argument (exception)@`Invalid_argument' (exception)
                Exception raised by library functions to signal that the given
               arguments do not make sense.

<<
  exception Failure of string
>>
   Failure (exception)@`Failure' (exception)
                Exception raised by library functions to signal that they are
               undefined on the given arguments.

<<
  exception Not_found
>>
   Not_found (exception)@`Not_found' (exception)
                Exception raised by search functions when the desired object
               could not be found.

<<
  exception Out_of_memory
>>
   Out_of_memory (exception)@`Out_of_memory' (exception)
                Exception raised by the garbage collector when there is
               insufficient memory to complete the computation.

<<
  exception Stack_overflow
>>
   Stack_overflow (exception)@`Stack_overflow' (exception)
                Exception raised by the bytecode interpreter when the
               evaluation stack reaches its maximal size. This often indicates
               infinite or excessively deep recursion in the user's program.

<<
  exception Sys_error of string
>>
   Sys_error (exception)@`Sys_error' (exception)
                Exception raised by the input/output functions to report an
               operating system error.

<<
  exception End_of_file
>>
   End_of_file (exception)@`End_of_file' (exception)
                Exception raised by input functions to signal that the end of
               file has been reached.

<<
  exception Division_by_zero
>>
   Division_by_zero (exception)@`Division_by_zero' (exception)
                Exception raised by division and remainder operations when
               their second argument is null.

<<
  exception Exit
>>
   Exit (exception)@`Exit' (exception)
                This exception is not raised by any library function. It is
               provided for use in your programs.

<<
  exception Sys_blocked_io
>>
   Sys_blocked_io (exception)@`Sys_blocked_io' (exception)
                A special case of `Sys_error' raised when no I/O is possible on
               a non-blocking I/O channel.

<<
  val invalid_arg: string -> 'a
>>
   invalid_arg@`invalid_arg'
                Raise exception `Invalid_argument' with the given string.

<<
  val failwith: string -> 'a
>>
   failwith@`failwith'
                Raise exception `Failure' with the given string.

Comparisons
=-=-=-=-=-=-

<<
  val (=) : 'a -> 'a -> bool
>>
   = (operator)@`=' (operator)
                `e1 = e2' tests for structural equality of `e1' and `e2'.
               Mutable structures (e.g. references and arrays) are equal if and
               only if their current contents are structurally equal, even if
               the two mutable objects are not the same physical object.
               Equality between functional values raises `Invalid_argument'.
               Equality between cyclic data structures may not terminate.

<<
  val (<>) : 'a -> 'a -> bool
>>
   <> (operator)@`<>' (operator)
                Negation of `(=)'.

<<
  val (<) : 'a -> 'a -> bool
  val (>) : 'a -> 'a -> bool
  val (<=) : 'a -> 'a -> bool
  val (>=) : 'a -> 'a -> bool
>>
   < (operator)@`<' (operator)> (operator)@`>' (operator)<= (operator)@`<='
(operator)>= (operator)@`>=' (operator)
                Structural ordering functions. These functions coincide with
               the usual orderings over integers, characters, strings and
               floating-point numbers, and extend them to a total ordering over
               all types. The ordering is compatible with `(=)'. As in the case
               of `(=)', mutable structures are compared by contents.
               Comparison between functional values raises `Invalid_argument'.
               Comparison between cyclic structures may not terminate.

<<
  val compare: 'a -> 'a -> int
>>
   compare@`compare'
                `compare x y' returns `0' if `x=y', a negative integer if
               `x<y', and a positive integer if `x>y'. The same restrictions as
               for `=' apply. `compare' can be used as the comparison function
               required by the `Set' and `Map' modules.

<<
  val min: 'a -> 'a -> 'a
>>
   min@`min'
                Return the smaller of the two arguments.

<<
  val max: 'a -> 'a -> 'a
>>
   max@`max'
                Return the greater of the two arguments.

<<
  val (==) : 'a -> 'a -> bool
>>
   == (operator)@`==' (operator)
                `e1 == e2' tests for physical equality of `e1' and `e2'. On
               integers and characters, it is the same as structural equality.
               On mutable structures, `e1 == e2' is true if and only if
               physical modification of `e1' also affects `e2'. On non-mutable
               structures, the behavior of `(==)' is implementation-dependent,
               except that `e1 == e2' implies `e1 = e2'.

<<
  val (!=) : 'a -> 'a -> bool
>>
   "!= (operator)@`"!=' (operator)
                Negation of `(==)'.

Boolean operations
=-=-=-=-=-=-=-=-=-=

<<
  val not : bool -> bool
>>
   not@`not'
                The boolean negation.

<<
  val (&&) : bool -> bool -> bool
  val (&) : bool -> bool -> bool
>>
   (operator)@`&&' (operator)(operator)@`&' (operator)
                The boolean ``and''. Evaluation is sequential, left-to-right:
               in `e1 && e2', `e1' is evaluated first, and if it returns
               `false', `e2' is not evaluated at all.

<<
  val (||) : bool -> bool -> bool
  val (or) : bool -> bool -> bool
>>
   "|"| (operator)@`"|"|' (operator)or (operator)@`or' (operator)
                The boolean ``or''. Evaluation is sequential, left-to-right: in
               `e1 || e2', `e1' is evaluated first, and if it returns `true',
               `e2' is not evaluated at all.

Integer arithmetic
=-=-=-=-=-=-=-=-=-=

                Integers are 31 bits wide (or 63 bits on 64-bit processors).
               All operations are taken modulo 2^31 (or 2^63). They do not fail
               on overflow.

<<
  val (~-) : int -> int
>>
    - (operator)@`~-' (operator)
                Unary negation. You can also write `-e' instead of `~-e'.

<<
  val succ : int -> int
>>
   succ@`succ'
                `succ x' is `x+1'.

<<
  val pred : int -> int
>>
   pred@`pred'
                `pred x' is `x-1'.

<<
  val (+) : int -> int -> int
>>
   + (operator)@`+' (operator)
                Integer addition.

<<
  val (-) : int -> int -> int
>>
   - (operator)@`-' (operator)
                Integer subtraction.

<<
  val (*) : int -> int -> int
>>
   * (operator)@`*' (operator)
                Integer multiplication.

<<
  val (/) : int -> int -> int
>>
   / (operator)@`/' (operator)
                Integer division. Raise `Division_by_zero' if the second
               argument is 0.

<<
  val (mod) : int -> int -> int
>>
   mod (operator)@`mod' (operator)
                Integer remainder. If `x >= 0' and `y > 0', the result of `x
               mod y' satisfies the following properties: `0 <= x mod y < y'
               and `x = (x / y) * y + x mod y'. If `y = 0', `x mod y' raises
               `Division_by_zero'. If `x < 0' or `y < 0', the result of `x mod
               y' is not specified and depends on the platform.

<<
  val abs : int -> int
>>
   abs@`abs'
                Return the absolute value of the argument.

<<
  val max_int: int
  val min_int: int
>>
   max_int@`max_int'min_int@`min_int'
                The greatest and smallest representable integers.

Bitwise operations
-------------------

<<
  val (land) : int -> int -> int
>>
   land (operator)@`land' (operator)
                Bitwise logical and.

<<
  val (lor) : int -> int -> int
>>
   lor (operator)@`lor' (operator)
                Bitwise logical or.

<<
  val (lxor) : int -> int -> int
>>
   lxor (operator)@`lxor' (operator)
                Bitwise logical exclusive or.

<<
  val lnot: int -> int
>>
   lnot@`lnot'
                Bitwise logical negation.

<<
  val (lsl) : int -> int -> int
>>
   lsl (operator)@`lsl' (operator)
                `n lsl m' shifts `n' to the left by `m' bits.

<<
  val (lsr) : int -> int -> int
>>
   lsr (operator)@`lsr' (operator)
                `n lsr m' shifts `n' to the right by `m' bits. This is a
               logical shift: zeroes are inserted regardless of the sign of
               `n'.

<<
  val (asr) : int -> int -> int
>>
   asr (operator)@`asr' (operator)
                `n asr m' shifts `n' to the right by `m' bits. This is an
               arithmetic shift: the sign bit of `n' is replicated.

Floating-point arithmetic
=-=-=-=-=-=-=-=-=-=-=-=-=-

                On most platforms, Caml's floating-point numbers follow the
               IEEE 754 standard, using double precision (64 bits) numbers.
               Floating-point operations do not fail on overflow or underflow,
               but return denormal numbers.

<<
  val (~-.) : float -> float
>>
    -. (operator)@`~-.' (operator)
                Unary negation. You can also write `-.e' instead of `~-.e'.

<<
  val (+.) : float -> float -> float
>>
   +. (operator)@`+.' (operator)
                Floating-point addition

<<
  val (-.) : float -> float -> float
>>
   -. (operator)@`-.' (operator)
                Floating-point subtraction

<<
  val (*.) : float -> float -> float
>>
   *. (operator)@`*.' (operator)
                Floating-point multiplication

<<
  val (/.) : float -> float -> float
>>
   /. (operator)@`/.' (operator)
                Floating-point division.

<<
  val (**) : float -> float -> float
>>
   ** (operator)@`**' (operator)
                Exponentiation

<<
  val sqrt : float -> float
>>
   sqrt@`sqrt'
                Square root

<<
  val exp : float -> float
  val log : float -> float
  val log10 : float -> float
>>
   exp@`exp'log@`log'log10@`log10'
                Exponential, natural logarithm, base 10 logarithm.

<<
  val cos : float -> float
  val sin : float -> float
  val tan : float -> float
  val acos : float -> float
  val asin : float -> float
  val atan : float -> float
  val atan2 : float -> float -> float
>>
   cos@`cos'sin@`sin'tan@`tan'acos@`acos'asin@`asin'atan@`atan'atan2@`atan2'
                The usual trignonmetric functions

<<
  val cosh : float -> float
  val sinh : float -> float
  val tanh : float -> float
>>
   cosh@`cosh'sinh@`sinh'tanh@`tanh'
                The usual hyperbolic trigonometric functions

<<
  val ceil : float -> float
  val floor : float -> float
>>
   ceil@`ceil'floor@`floor'
                Round the given float to an integer value. `floor f' returns
               the greatest integer value less than or equal to `f'. `ceil f'
               returns the least integer value greater than or equal to `f'.

<<
  val abs_float : float -> float
>>
   abs_float@`abs_float'
                Return the absolute value of the argument.

<<
  val mod_float : float -> float -> float
>>
   mod_float@`mod_float'
                `mod_float a b' returns the remainder of `a' with respect to
               `b'. The returned value is `a -. n *. b', where `n' is the
               quotient `a /. b' rounded towards zero to an integer.

<<
  val frexp : float -> float * int
>>
   frexp@`frexp'
                `frexp f' returns the pair of the significant and the exponent
               of `f'. When `f' is zero, the significant `x' and the exponent
               `n' of `f' are equal to zero. When `f' is non-zero, they are
               defined by `f = x *. 2 ** n' and `0.5 <= x < 1.0'.

<<
  val ldexp : float -> int -> float
>>
   ldexp@`ldexp'
                `ldexp x n' returns `x *. 2 ** n'.

<<
  val modf : float -> float * float
>>
   modf@`modf'
                `modf f' returns the pair of the fractional and integral part
               of `f'.

<<
  val float : int -> float
  val float_of_int : int -> float
>>
   float@`float'float_of_int@`float_of_int'
                Convert an integer to floating-point.

<<
  val truncate : float -> int
  val int_of_float : float -> int
>>
   truncate@`truncate'int_of_float@`int_of_float'
                Truncate the given floating-point number to an integer. The
               result is unspecified if it falls outside the range of
               representable integers.

String operations
=-=-=-=-=-=-=-=-=-

                More string operations are provided in module `String'.

<<
  val (^) : string -> string -> string
>>
   ^ (operator)@`^' (operator)
                String concatenation.

Character operations
=-=-=-=-=-=-=-=-=-=-=

                More character operations are provided in module `Char'.

<<
  val int_of_char : char -> int
>>
   int_of_char@`int_of_char'
                Return the ASCII code of the argument.

<<
  val char_of_int : int -> char
>>
   char_of_int@`char_of_int'
                Return the character with the given ASCII code. Raise
               `Invalid_argument "char_of_int"' if the argument is outside the
               range 0--255.

Unit operations
=-=-=-=-=-=-=-=-

<<
  val ignore : 'a -> unit
>>
   ignore@`ignore'
                Discard the value of its argument and return `()'. For
               instance, `ignore(f x)' discards the result of the
               side-effecting function `f'. It is equivalent to `f x; ()',
               except that no warning is generated.

String conversion functions
=-=-=-=-=-=-=-=-=-=-=-=-=-=-

<<
  val string_of_bool : bool -> string
>>
   string_of_bool@`string_of_bool'
                Return the string representation of a boolean.

<<
  val bool_of_string : string -> bool
>>
   bool_of_string@`bool_of_string'
                Convert the given string to a boolean. Raise `Invalid_argument
               "bool_of_string"' if the string is not `"true"' or `"false"'.

<<
  val string_of_int : int -> string
>>
   string_of_int@`string_of_int'
                Return the string representation of an integer, in decimal.

<<
  val int_of_string : string -> int
>>
   int_of_string@`int_of_string'
                Convert the given string to an integer. The string is read in
               decimal (by default) or in hexadecimal, octal or binary if the
               string begins with `0x', `0o' or `0b' respectively. Raise
               `Failure "int_of_string"' if the given string is not a valid
               representation of an integer.

<<
  val string_of_float : float -> string
>>
   string_of_float@`string_of_float'
                Return the string representation of a floating-point number.

<<
  val float_of_string : string -> float
>>
   float_of_string@`float_of_string'
                Convert the given string to a float. The result is unspecified
               if the given string is not a valid representation of a float.

Pair operations
=-=-=-=-=-=-=-=-

<<
  val fst : 'a * 'b -> 'a
>>
   fst@`fst'
                Return the first component of a pair.

<<
  val snd : 'a * 'b -> 'b
>>
   snd@`snd'
                Return the second component of a pair.

List operations
=-=-=-=-=-=-=-=-

                More list operations are provided in module `List'.

<<
  val (@) : 'a list -> 'a list -> 'a list
>>
   "@ (operator)@`"@' (operator)
                List concatenation.

Input/output
=-=-=-=-=-=-=

<<
  type in_channel
  type out_channel
>>

                The types of input channels and output channels.

<<
  val stdin : in_channel
  val stdout : out_channel
  val stderr : out_channel
>>
   stdin@`stdin'stdout@`stdout'stderr@`stderr'
                The standard input, standard output, and standard error output
               for the process.

Output functions on standard output
------------------------------------

<<
  val print_char : char -> unit
>>
   print_char@`print_char'
                Print a character on standard output.

<<
  val print_string : string -> unit
>>
   print_string@`print_string'
                Print a string on standard output.

<<
  val print_int : int -> unit
>>
   print_int@`print_int'
                Print an integer, in decimal, on standard output.

<<
  val print_float : float -> unit
>>
   print_float@`print_float'
                Print a floating-point number, in decimal, on standard output.

<<
  val print_endline : string -> unit
>>
   print_endline@`print_endline'
                Print a string, followed by a newline character, on standard
               output.

<<
  val print_newline : unit -> unit
>>
   print_newline@`print_newline'
                Print a newline character on standard output, and flush
               standard output. This can be used to simulate line buffering of
               standard output.

Output functions on standard error
-----------------------------------

<<
  val prerr_char : char -> unit
>>
   prerr_char@`prerr_char'
                Print a character on standard error.

<<
  val prerr_string : string -> unit
>>
   prerr_string@`prerr_string'
                Print a string on standard error.

<<
  val prerr_int : int -> unit
>>
   prerr_int@`prerr_int'
                Print an integer, in decimal, on standard error.

<<
  val prerr_float : float -> unit
>>
   prerr_float@`prerr_float'
                Print a floating-point number, in decimal, on standard error.

<<
  val prerr_endline : string -> unit
>>
   prerr_endline@`prerr_endline'
                Print a string, followed by a newline character on standard
               error and flush standard error.

<<
  val prerr_newline : unit -> unit
>>
   prerr_newline@`prerr_newline'
                Print a newline character on standard error, and flush standard
               error.

Input functions on standard input
----------------------------------

<<
  val read_line : unit -> string
>>
   read_line@`read_line'
                Flush standard output, then read characters from standard input
               until a newline character is encountered. Return the string of
               all characters read, without the newline character at the end.

<<
  val read_int : unit -> int
>>
   read_int@`read_int'
                Flush standard output, then read one line from standard input
               and convert it to an integer. Raise `Failure "int_of_string"' if
               the line read is not a valid representation of an integer.

<<
  val read_float : unit -> float
>>
   read_float@`read_float'
                Flush standard output, then read one line from standard input
               and convert it to a floating-point number. The result is
               unspecified if the line read is not a valid representation of a
               floating-point number.

General output functions
-------------------------

<<
  type open_flag =
      Open_rdonly | Open_wronly | Open_append
    | Open_creat | Open_trunc | Open_excl
    | Open_binary | Open_text | Open_nonblock
>>

                Opening modes for `open_out_gen' and `open_in_gen'.
               `Open_rdonly': open for reading.
               `Open_wronly': open for writing.
               `Open_append': open for appending.
               `Open_creat': create the file if it does not exist.
               `Open_trunc': empty the file if it already exists.
               `Open_excl': fail if the file already exists.
               `Open_binary': open in binary mode (no conversion).
               `Open_text': open in text mode (may perform conversions).
               `Open_nonblock': open in non-blocking mode.

<<

  val open_out : string -> out_channel
>>
   open_out@`open_out'
                Open the named file for writing, and return a new output
               channel on that file, positionned at the beginning of the file.
               The file is truncated to zero length if it already exists. It is
               created if it does not already exists. Raise `Sys_error' if the
               file could not be opened.

<<
  val open_out_bin : string -> out_channel
>>
   open_out_bin@`open_out_bin'
                Same as `open_out', but the file is opened in binary mode, so
               that no translation takes place during writes. On operating
               systems that do not distinguish between text mode and binary
               mode, this function behaves like `open_out'.

<<
  val open_out_gen : open_flag list -> int -> string -> out_channel
>>
   open_out_gen@`open_out_gen'
                `open_out_gen mode rights filename' opens the file named
               `filename' for writing, as above. The extra argument `mode'
               specify the opening mode. The extra argument `rights' specifies
               the file permissions, in case the file must be created.
               `open_out' and `open_out_bin' are special cases of this
               function.

<<
  val flush : out_channel -> unit
>>
   flush@`flush'
                Flush the buffer associated with the given output channel,
               performing all pending writes on that channel. Interactive
               programs must be careful about flushing standard output and
               standard error at the right time.

<<
  val output_char : out_channel -> char -> unit
>>
   output_char@`output_char'
                Write the character on the given output channel.

<<
  val output_string : out_channel -> string -> unit
>>
   output_string@`output_string'
                Write the string on the given output channel.

<<
  val output : out_channel -> string -> int -> int -> unit
>>
   output@`output'
                `output chan buff ofs len' writes `len' characters from string
               `buff', starting at offset `ofs', to the output channel `chan'.
               Raise `Invalid_argument "output"' if `ofs' and `len' do not
               designate a valid substring of `buff'.

<<
  val output_byte : out_channel -> int -> unit
>>
   output_byte@`output_byte'
                Write one 8-bit integer (as the single character with that
               code) on the given output channel. The given integer is taken
               modulo 256.

<<
  val output_binary_int : out_channel -> int -> unit
>>
   output_binary_int@`output_binary_int'
                Write one integer in binary format on the given output channel.
               The only reliable way to read it back is through the
               `input_binary_int' function. The format is compatible across all
               machines for a given version of Objective Caml.

<<
  val output_value : out_channel -> 'a -> unit
>>
   output_value@`output_value'
                Write the representation of a structured value of any type to a
               channel. Circularities and sharing inside the value are detected
               and preserved. The object can be read back, by the function
               `input_value'. See the description of module `Marshal' for more
               information. `output_value' is equivalent to
               `Marshal.to_channel' with an empty list of flags.

<<
  val seek_out : out_channel -> int -> unit
>>
   seek_out@`seek_out'
                `seek_out chan pos' sets the current writing position to `pos'
               for channel `chan'. This works only for regular files. On files
               of other kinds (such as terminals, pipes and sockets), the
               behavior is unspecified.

<<
  val pos_out : out_channel -> int
>>
   pos_out@`pos_out'
                Return the current writing position for the given channel.

<<
  val out_channel_length : out_channel -> int
>>
   out_channel_length@`out_channel_length'
                Return the total length (number of characters) of the given
               channel. This works only for regular files. On files of other
               kinds, the result is meaningless.

<<
  val close_out : out_channel -> unit
>>
   close_out@`close_out'
                Close the given channel, flushing all buffered write
               operations. The behavior is unspecified if any of the functions
               above is called on a closed channel.

<<
  val set_binary_mode_out : out_channel -> bool -> unit
>>
   set_binary_mode_out@`set_binary_mode_out'
                `set_binary_mode_out oc true' sets the channel `oc' to binary
               mode: no translations take place during output.
               `set_binary_mode_out oc false' sets the channel `oc' to text
               mode: depending on the operating system, some translations may
               take place during output. For instance, under Windows,
               end-of-lines will be translated from `\n' to `\r\n'. This
               function has no effect under operating systems that do not
               distinguish between text mode and binary mode.

General input functions
------------------------

<<
  val open_in : string -> in_channel
>>
   open_in@`open_in'
                Open the named file for reading, and return a new input channel
               on that file, positionned at the beginning of the file. Raise
               `Sys_error' if the file could not be opened.

<<
  val open_in_bin : string -> in_channel
>>
   open_in_bin@`open_in_bin'
                Same as `open_in', but the file is opened in binary mode, so
               that no translation takes place during reads. On operating
               systems that do not distinguish between text mode and binary
               mode, this function behaves like `open_in'.

<<
  val open_in_gen : open_flag list -> int -> string -> in_channel
>>
   open_in_gen@`open_in_gen'
                `open_in_gen mode rights filename' opens the file named
               `filename' for reading, as above. The extra arguments `mode' and
               `rights' specify the opening mode and file permissions.
               `open_in' and `open_in_bin' are special cases of this function.

<<
  val input_char : in_channel -> char
>>
   input_char@`input_char'
                Read one character from the given input channel. Raise
               `End_of_file' if there are no more characters to read.

<<
  val input_line : in_channel -> string
>>
   input_line@`input_line'
                Read characters from the given input channel, until a newline
               character is encountered. Return the string of all characters
               read, without the newline character at the end. Raise
               `End_of_file' if the end of the file is reached at the beginning
               of line.

<<
  val input : in_channel -> string -> int -> int -> int
>>
   input@`input'
                `input chan buff ofs len' attempts to read `len' characters
               from channel `chan', storing them in string `buff', starting at
               character number `ofs'. It returns the actual number of
               characters read, between 0 and `len' (inclusive). A return value
               of 0 means that the end of file was reached. A return value
               between 0 and `len' exclusive means that no more characters were
               available at that time; `input' must be called again to read the
               remaining characters, if desired. Exception `Invalid_argument
               "input"' is raised if `ofs' and `len' do not designate a valid
               substring of `buff'.

<<
  val really_input : in_channel -> string -> int -> int -> unit
>>
   really_input@`really_input'
                `really_input chan buff ofs len' reads `len' characters from
               channel `chan', storing them in string `buff', starting at
               character number `ofs'. Raise `End_of_file' if the end of file
               is reached before `len' characters have been read. Raise
               `Invalid_argument "really_input"' if `ofs' and `len' do not
               designate a valid substring of `buff'.

<<
  val input_byte : in_channel -> int
>>
   input_byte@`input_byte'
                Same as `input_char', but return the 8-bit integer representing
               the character. Raise `End_of_file' if an end of file was
               reached.

<<
  val input_binary_int : in_channel -> int
>>
   input_binary_int@`input_binary_int'
                Read an integer encoded in binary format from the given input
               channel. See `output_binary_int'. Raise `End_of_file' if an end
               of file was reached while reading the integer.

<<
  val input_value : in_channel -> 'a
>>
   input_value@`input_value'
                Read the representation of a structured value, as produced by
               `output_value', and return the corresponding value. This
               function is identical to `Marshal.from_channel'; see the
               description of module `Marshal' for more information, in
               particular concerning the lack of type safety.

<<
  val seek_in : in_channel -> int -> unit
>>
   seek_in@`seek_in'
                `seek_in chan pos' sets the current reading position to `pos'
               for channel `chan'. This works only for regular files. On files
               of other kinds, the behavior is unspecified.

<<
  val pos_in : in_channel -> int
>>
   pos_in@`pos_in'
                Return the current reading position for the given channel.

<<
  val in_channel_length : in_channel -> int
>>
   in_channel_length@`in_channel_length'
                Return the total length (number of characters) of the given
               channel. This works only for regular files. On files of other
               kinds, the result is meaningless.

<<
  val close_in : in_channel -> unit
>>
   close_in@`close_in'
                Close the given channel. Anything can happen if any of the
               functions above is called on a closed channel.

<<
  val set_binary_mode_in : in_channel -> bool -> unit
>>
   set_binary_mode_in@`set_binary_mode_in'
                `set_binary_mode_in ic true' sets the channel `ic' to binary
               mode: no translations take place during input.
               `set_binary_mode_out ic false' sets the channel `ic' to text
               mode: depending on the operating system, some translations may
               take place during input. For instance, under Windows,
               end-of-lines will be translated from `\r\n' to `\n'. This
               function has no effect under operating systems that do not
               distinguish between text mode and binary mode.

References
=-=-=-=-=-=

<<
  type 'a ref = { mutable contents: 'a }
>>

                The type of references (mutable indirection cells) containing a
               value of type `'a'.

<<
  val ref : 'a -> 'a ref
>>
   ref@`ref'
                Return a fresh reference containing the given value.

<<
  val (!) : 'a ref -> 'a
>>
   "! (operator)@`"!' (operator)
                `!r' returns the current contents of reference `r'. Equivalent
               to `fun r -> r.contents'.

<<
  val (:=) : 'a ref -> 'a -> unit
>>
   := (operator)@`:=' (operator)
                `r := a' stores the value of `a' in reference `r'. Equivalent
               to `fun r v -> r.contents <- v'.

<<
  val incr : int ref -> unit
>>
   incr@`incr'
                Increment the integer contained in the given reference.
               Equivalent to `fun r -> r := succ !r'.

<<
  val decr : int ref -> unit
>>
   decr@`decr'
                Decrement the integer contained in the given reference.
               Equivalent to `fun r -> r := pred !r'.

Program termination
=-=-=-=-=-=-=-=-=-=-

<<
  val exit : int -> 'a
>>
   exit@`exit'
                Flush all pending writes on `stdout' and `stderr', and
               terminate the process, returning the given status code to the
               operating system (usually 0 to indicate no errors, and a small
               positive integer to indicate failure.)  An implicit `exit 0' is
               performed each time a program terminates normally (but not if it
               terminates because of an uncaught exception).

<<
  val at_exit: (unit -> unit) -> unit
>>
   at_exit@`at_exit'
                Register the given function to be called at program termination
               time. The functions registered with `at_exit' will be called
               when the program executes `exit'.  They will not be called if
               the program terminates because of an uncaught exception. The
               functions are called in ``last in, first out'' order: the
               function most recently added with `at_exit' is called first.

Chapter 17    The standard library
**********************************

  This chapter describes the functions provided by the Caml Light standard
library. The modules from the standard library are automatically linked with
the user's object code files by the ocamlc command. Hence, these modules can be
used in standalone programs without having to add any .cmo file on the command
line for the linking phase. Similarly, in interactive use, these globals can be
used in toplevel phrases without having to load any .cmo file in memory.
  Unlike the Pervasive module from the core library, the modules from the
standard library are not automatically ``opened'' when a compilation starts, or
when the toplevel system is launched. Hence it is necessary to use qualified
identifiers to refer to the functions provided by these modules, or to add open
directives.
Conventions
===========

  For easy reference, the modules are listed below in alphabetical order of
module names. For each module, the declarations from its signature are printed
one by one in typewriter font, followed by a short comment. All modules and the
identifiers they export are indexed at the end of this report.

17.1  Module Arg: parsing of command line arguments
===================================================

   Arg (module)@`Arg' (module)
                This module provides a general mechanism for extracting options
               and arguments from the command line to the program.

                Syntax of command lines: A keyword is a character string
               starting with a `-'. An option is a keyword alone or followed by
               an argument. The types of keywords are: `Unit', `Set', `Clear',
               `String', `Int', `Float', and `Rest'. `Unit', `Set' and `Clear'
               keywords take no argument. `String', `Int', and `Float' keywords
               take the following word on the command line as an argument. A
               `Rest' keyword takes the remaining of the command line as
               (string) arguments. Arguments not preceded by a keyword are
               called anonymous arguments.

                Examples (`cmd' is assumed to be the command name):
               `cmd -flag           '(a unit option)
               `cmd -int 1          '(an int option with argument `1')
               `cmd -string foobar  '(a string option with argument `"foobar"')

               `cmd -float 12.34    '(a float option with argument `12.34')
               `cmd a b c           '(three anonymous arguments: `"a"', `"b"',
               and `"c"')
               `cmd a b -- c d      '(two anonymous arguments and a rest option
               with
               `                    ' two arguments)

<<
  type spec =
    | Unit of (unit -> unit)     (* Call the function with unit argument *)
    | Set of bool ref            (* Set the reference to true *)
    | Clear of bool ref          (* Set the reference to false *)
    | String of (string -> unit) (* Call the function with a string argument *)
    | Int of (int -> unit)       (* Call the function with an int argument *)
    | Float of (float -> unit)   (* Call the function with a float argument *)
    | Rest of (string -> unit)   (* Stop interpreting keywords and call the
                                    function with each remaining argument *)
>>

                The concrete type describing the behavior associated with a
               keyword.

<<
  val parse : (string * spec * string) list -> (string -> unit) -> string ->
unit
>>
   parse@`parse'
               `Arg.parse speclist anonfun usage_msg' parses the command line.
               `speclist' is a list of triples `(key, spec, doc)'. `key' is the
               option keyword, it must start with a `'-'' character. `spec'
               gives the option type and the function to call when this option
               is found on the command line. `doc' is a one-line description of
               this option. `anonfun' is called on anonymous arguments. The
               functions in `spec' and `anonfun' are called in the same order
               as their arguments appear on the command line.If an error
               occurs, `Arg.parse' exits the program, after printing an error
               message as follows:
               The reason for the error: unknown option, invalid or missing
               argument, etc.
               `usage_msg'
               The list of options, each followed by the corresponding `doc'
               string.For the user to be able to specify anonymous arguments
               starting with a `-', include for example `("-", String anonfun,
               doc)' in `speclist'.By default, `parse' recognizes a unit option
               `-help', which will display `usage_msg' and the list of options,
               and exit the program. You can override this behaviour by
               specifying your own `-help' option in `speclist'.

<<
  exception Bad of string
>>
   Bad (exception)@`Bad' (exception)
               Functions in `spec' or `anonfun' can raise `Arg.Bad' with an
               error message to reject invalid arguments.

<<
  val usage: (string * spec * string) list -> string -> unit
>>
   usage@`usage'
               `Arg.usage speclist usage_msg' prints an error message including
               the list of valid options. This is the same message that
               `Arg.parse' prints in case of error. `speclist' and `usage_msg'
               are the same as for `Arg.parse'.

<<
  val current: int ref;;
>>
   current@`current'
               Position (in `Sys.argv') of the argument being processed. You
               can change this value, e.g. to force `Arg.parse' to skip some
               arguments.

17.2  Module Array: array operations
====================================

   Array (module)@`Array' (module)
<<
  val length : 'a array -> int
>>
   length@`length'
                Return the length (number of elements) of the given array.

<<
  val get: 'a array -> int -> 'a
>>
   get@`get'
                `Array.get a n' returns the element number `n' of array `a'.
               The first element has number 0. The last element has number
               `Array.length a - 1'. Raise `Invalid_argument "Array.get"' if
               `n' is outside the range 0 to `(Array.length a - 1)'. You can
               also write `a.(n)' instead of `Array.get a n'.

<<
  val set: 'a array -> int -> 'a -> unit
>>
   set@`set'
                `Array.set a n x' modifies array `a' in place, replacing
               element number `n' with `x'. Raise `Invalid_argument
               "Array.set"' if `n' is outside the range 0 to `Array.length a -
               1'. You can also write `a.(n) <- x' instead of `Array.set a n
               x'.

<<
  val make: int -> 'a -> 'a array
  val create: int -> 'a -> 'a array
>>
   make@`make'create@`create'
                `Array.make n x' returns a fresh array of length `n',
               initialized with `x'. All the elements of this new array are
               initially physically equal to `x' (in the sense of the `=='
               predicate). Consequently, if `x' is mutable, it is shared among
               all elements of the array, and modifying `x' through one of the
               array entries will modify all other entries at the same time.
               Raise `Invalid_argument' if `n <= 0' or `n >
               Sys.max_array_length'. If the value of `x' is a floating-point
               number, then the maximum size is only `Sys.max_array_length /
               2'. `Array.create' is a deprecated alias for `Array.make'.

<<
  val init: int -> (int -> 'a) -> 'a array
>>
   init@`init'
                `Array.init n f' returns a fresh array of length `n', with
               element number `i' initialized to the result of `f i'. In other
               terms, `Array.init n f' tabulates the results of `f' applied to
               the integers `0' to `n-1'.

<<
  val make_matrix: int -> int -> 'a -> 'a array array
  val create_matrix: int -> int -> 'a -> 'a array array
>>
   make_matrix@`make_matrix'create_matrix@`create_matrix'
                `Array.make_matrix dimx dimy e' returns a two-dimensional array
               (an array of arrays) with first dimension `dimx' and second
               dimension `dimy'. All the elements of this new matrix are
               initially physically equal to `e'. The element (`x,y') of a
               matrix `m' is accessed with the notation `m.(x).(y)'. Raise
               `Invalid_argument' if `dimx' or `dimy' is less than 1 or greater
               than `Sys.max_array_length'. If the value of `e' is a
               floating-point number, then the maximum size is only
               `Sys.max_array_length / 2'. `Array.create_matrix' is a
               deprecated alias for `Array.make_matrix'.

<<
  val append: 'a array -> 'a array -> 'a array
>>
   append@`append'
                `Array.append v1 v2' returns a fresh array containing the
               concatenation of the arrays `v1' and `v2'.

<<
  val concat: 'a array list -> 'a array
>>
   concat@`concat'
                Same as `Array.append', but catenates a list of arrays.

<<
  val sub: 'a array -> int -> int -> 'a array
>>
   sub@`sub'
                `Array.sub a start len' returns a fresh array of length `len',
               containing the elements number `start' to `start + len - 1' of
               array `a'. Raise `Invalid_argument "Array.sub"' if `start' and
               `len' do not designate a valid subarray of `a'; that is, if
               `start < 0', or `len < 0', or `start + len > Array.length a'.

<<
  val copy: 'a array -> 'a array
>>
   copy@`copy'
                `Array.copy a' returns a copy of `a', that is, a fresh array
               containing the same elements as `a'.

<<
  val fill: 'a array -> int -> int -> 'a -> unit
>>
   fill@`fill'
                `Array.fill a ofs len x' modifies the array `a' in place,
               storing `x' in elements number `ofs' to `ofs + len - 1'. Raise
               `Invalid_argument "Array.fill"' if `ofs' and `len' do not
               designate a valid subarray of `a'.

<<
  val blit: 'a array -> int -> 'a array -> int -> int -> unit
>>
   blit@`blit'
                `Array.blit v1 o1 v2 o2 len' copies `len' elements from array
               `v1', starting at element number `o1', to array `v2', starting
               at element number `o2'. It works correctly even if `v1' and `v2'
               are the same array, and the source and destination chunks
               overlap. Raise `Invalid_argument "Array.blit"' if `o1' and `len'
               do not designate a valid subarray of `v1', or if `o2' and `len'
               do not designate a valid subarray of `v2'.

<<
  val to_list: 'a array -> 'a list
>>
   to_list@`to_list'
                `Array.to_list a' returns the list of all the elements of `a'.

<<
  val of_list: 'a list -> 'a array
>>
   of_list@`of_list'
                `Array.of_list l' returns a fresh array containing the elements
               of `l'.

<<
  val iter: ('a -> unit) -> 'a array -> unit
>>
   iter@`iter'
                `Array.iter f a' applies function `f' in turn to all the
               elements of `a'. It is equivalent to `f a.(0); f a.(1); ...; f
               a.(Array.length a - 1); ()'.

<<
  val map: ('a -> 'b) -> 'a array -> 'b array
>>
   map@`map'
                `Array.map f a' applies function `f' to all the elements of
               `a', and builds an array with the results returned by `f': `[| f
               a.(0); f a.(1); ...; f a.(Array.length a - 1) |]'.

<<
  val iteri: (int -> 'a -> unit) -> 'a array -> unit
  val mapi: (int -> 'a -> 'b) -> 'a array -> 'b array
>>
   iteri@`iteri'mapi@`mapi'
                Same as `Array.iter' and `Array.map' respectively, but the
               function is applied to the index of the element as first
               argument, and the element itself as second argument.

<<
  val fold_left: ('a -> 'b -> 'a) -> 'a -> 'b array -> 'a
>>
   fold_left@`fold_left'
                `Array.fold_left f x a' computes `f (... (f (f x a.(0)) a.(1))
               ...) a.(n-1)', where `n' is the length of the array `a'.

<<
  val fold_right: ('b -> 'a -> 'a) -> 'b array -> 'a -> 'a
>>
   fold_right@`fold_right'
                `Array.fold_right f a x' computes `f a.(0) (f a.(1) ( ... (f
               a.(n-1) x) ...))', where `n' is the length of the array `a'.

17.3  Module Buffer: extensible string buffers
==============================================

   Buffer (module)@`Buffer' (module)
                This module implements string buffers that automatically expand
               as necessary. It provides accumulative concatenation of strings
               in quasi-linear time (instead of quadratic time when strings are
               concatenated pairwise).

<<
  type t
>>

                The abstract type of buffers.

<<
  val create : int -> t
>>
   create@`create'
                `create n' returns a fresh buffer, initially empty. The `n'
               parameter is the initial size of the internal string that holds
               the buffer contents. That string is automatically reallocated
               when more than `n' characters are stored in the buffer, but
               shrinks back to `n' characters when `reset' is called. For best
               performance, `n' should be of the same order of magnitude as the
               number of characters that are expected to be stored in the
               buffer (for instance, 80 for a buffer that holds one output
               line). Nothing bad will happen if the buffer grows beyond that
               limit, however. In doubt, take `n = 16' for instance. If `n' is
               not between 1 and `Sys.max_string_length', it will be clipped to
               that interval.

<<
  val contents : t -> string
>>
   contents@`contents'
                Return a copy of the current contents of the buffer. The buffer
               itself is unchanged.

<<
  val length : t -> int
>>
   length@`length'
                Return the number of characters currently contained in the
               buffer.

<<
  val clear : t -> unit
>>
   clear@`clear'
                Empty the buffer.

<<
  val reset : t -> unit
>>
   reset@`reset'
                Empty the buffer and deallocate the internal string holding the
               buffer contents, replacing it with the initial internal string
               of length `n' that was allocated by `create n'. For long-lived
               buffers that may have grown a lot, `reset' allows faster
               reclaimation of the space used by the buffer.

<<
  val add_char : t -> char -> unit
>>
   add_char@`add_char'
                `add_char b c' appends the character `c' at the end of the
               buffer `b'.

<<
  val add_string : t -> string -> unit
>>
   add_string@`add_string'
                `add_string b s' appends the string `s' at the end of the
               buffer `b'.

<<
  val add_substring : t -> string -> int -> int -> unit
>>
   add_substring@`add_substring'
                `add_substring b s ofs len' takes `len' characters from offset
               `ofs' in string `s' and appends them at the end of the buffer
               `b'.

<<
  val add_buffer : t -> t -> unit
>>
   add_buffer@`add_buffer'
                `add_buffer b1 b2' appends the current contents of buffer `b2'
               at the end of buffer `b1'. `b2' is not modified.

<<
  val add_channel : t -> in_channel -> int -> unit
>>
   add_channel@`add_channel'
                `add_channel b ic n' reads exactly `n' character from the input
               channel `ic' and stores them at the end of buffer `b'. Raise
               `End_of_file' if the channel contains fewer than `n' characters.

<<
  val output_buffer : out_channel -> t -> unit
>>
   output_buffer@`output_buffer'
                `output_buffer oc b' writes the current contents of buffer `b'
               on the output channel `oc'.

17.4  Module Callback: registering Caml values with the C runtime
=================================================================

   Callback (module)@`Callback' (module)
                This module allows Caml values to be registered with the C
               runtime under a symbolic name, so that C code can later call
               back registered Caml functions, or raise registered Caml
               exceptions.

<<
  val register: string -> 'a -> unit
>>
   register@`register'
                `Callback.register n v' registers the value `v' under the name
               `n'. C code can later retrieve a handle to `v' by calling
               `caml_named_value(n)'.

<<
  val register_exception: string -> exn -> unit
>>
   register_exception@`register_exception'
                `Callback.register_exception n exn' registers the exception
               contained in the exception value `exn' under the name `n'. C
               code can later retrieve a handle to the exception by calling
               `caml_named_value(n)'. The exception value thus obtained is
               suitable for passign as first argument to `raise_constant' or
               `raise_with_arg'.

17.5  Module Char: character operations
=======================================

   Char (module)@`Char' (module)
<<
  val code : char -> int
>>
   code@`code'
                Return the ASCII code of the argument.

<<
  val chr: int -> char
>>
   chr@`chr'
                Return the character with the given ASCII code. Raise
               `Invalid_argument "Char.chr"' if the argument is outside the
               range 0--255.

<<
  val escaped : char -> string
>>
   escaped@`escaped'
                Return a string representing the given character, with special
               characters escaped following the lexical conventions of
               Objective Caml.

<<
  val lowercase: char -> char
  val uppercase: char -> char
>>
   lowercase@`lowercase'uppercase@`uppercase'
                Convert the given character to its equivalent lowercase or
               uppercase character, respectively.

17.6  Module Digest: MD5 message digest
=======================================

   Digest (module)@`Digest' (module)
                This module provides functions to compute 128-bit ``digests''
               of arbitrary-length strings or files. The digests are of
               cryptographic quality: it is very hard, given a digest, to forge
               a string having that digest. The algorithm used is MD5.

<<
  type t = string
>>

                The type of digests: 16-character strings.

<<
  val string: string -> t
>>
   string@`string'
                Return the digest of the given string.

<<
  val substring: string -> int -> int -> t
>>
   substring@`substring'
                `Digest.substring s ofs len' returns the digest of the
               substring of `s' starting at character number `ofs' and
               containing `len' characters.

<<
  val channel: in_channel -> int -> t
>>
   channel@`channel'
                `Digest.channel ic len' reads `len' characters from channel
               `ic' and returns their digest.

<<
  val file: string -> t
>>
   file@`file'
                Return the digest of the file whose name is given.

<<
  val output: out_channel -> t -> unit
>>
   output@`output'
                Write a digest on the given output channel.

<<
  val input: in_channel -> t
>>
   input@`input'
                Read a digest from the given input channel.

17.7  Module Filename: operations on file names
===============================================

   Filename (module)@`Filename' (module)
<<
  val current_dir_name : string
>>
   current_dir_name@`current_dir_name'
                The conventional name for the current directory (e.g. `.' in
               Unix).

<<
  val concat : string -> string -> string
>>
   concat@`concat'
                `concat dir file' returns a file name that designates file
               `file' in directory `dir'.

<<
  val is_relative : string -> bool
>>
   is_relative@`is_relative'
                Return `true' if the file name is relative to the current
               directory, `false' if it is absolute (i.e. in Unix, starts with
               `/'.

<<
  val is_implicit : string -> bool
>>
   is_implicit@`is_implicit'
                Return `true' if the file name is relative and does not start
               with an explicit reference to the current directory (`./' or
               `../' in Unix), `false' if it starts with an explicit reference
               to the root directory or the current directory.

<<
  val check_suffix : string -> string -> bool
>>
   check_suffix@`check_suffix'
                `check_suffix name suff' returns `true' if the filename `name'
               ends with the suffix `suff'.

<<
  val chop_suffix : string -> string -> string
>>
   chop_suffix@`chop_suffix'
                `chop_suffix name suff' removes the suffix `suff' from  the
               filename `name'. The behavior is undefined if `name' does not
               end with the suffix `suff'.

<<
  val chop_extension : string -> string
>>
   chop_extension@`chop_extension'
                Return the given file name without its extension. The extension
               is the shortest suffix starting with a period, `.xyz' for
               instance. Raise `Invalid_argument' if the given name does not
               contain a period.

<<
  val basename : string -> string
  val dirname : string -> string
>>
   basename@`basename'dirname@`dirname'
                Split a file name into directory name / base file name. `concat
               (dirname name) (basename name)' returns a file name which is
               equivalent to `name'. Moreover, after setting the current
               directory to `dirname name' (with `Sys.chdir'), references to
               `basename name' (which is a relative file name) designate the
               same file as `name' before the call to `Sys.chdir'.

<<
  val temp_file: string -> string -> string
>>
   temp_file@`temp_file'
                `temp_file prefix suffix' returns the name of a non-existent
               temporary file in the temporary directory. The base name of the
               temporary file is formed by concatenating `prefix', then a
               suitably chosen integer number, then `suffix'. Under Unix, the
               temporary directory is `/tmp' by default; if set, the value of
               the environment variable `TMPDIR' is used instead. Under
               Windows, the name of the temporary directory is the value of the
               environment variable `TEMP', or `C:\temp' by default. Under
               MacOS, the name of the temporary directory is given by the
               environment variable `TempFolder'; if not set, temporary files
               are created in the current directory.

17.8  Module Format: pretty printing
====================================

   Format (module)@`Format' (module)
                This module implements a pretty-printing facility to format
               text within ``pretty-printing boxes''. The pretty-printer breaks
               lines at specified break hints, and indents lines according to
               the box structure.

                You may consider this module as providing an extension to the
               `printf' facility to provide automatic line breaking. The
               addition of pretty-printing annotations to your regular `printf'
               formats gives you fancy indentation and line breaks.
               Pretty-printing annotations are described below in the
               documentation of the function `fprintf'.You may also use the
               explicit box management and printing functions provided by this
               module. This style is more basic but more verbose than the
               `fprintf' concise formats.For instance, the sequence  `open_box
               (); print_string "x ="; print_space (); print_int 1; close_box
               ()' that prints `x = 1' within a pretty-printing box, can be
               abbreviated as `printf "@[%s@ %i@]" "x =" 1'.

                Rule of thumb for casual users of this library:
               use simple boxes (as obtained by `open_box 0');
               use simple break hints (as obtained by `print_cut ()' that
               outputs a simple break hint, or by `print_space ()' that outputs
               a space indicating a break hint);
               once a box is opened, display its material with basic printing
               functions (e. g. `print_int' and `print_string');
               when the material for a box has been printed, call `close_box
               ()' to close the box;
               at the end of your routine, evaluate `print_newline ()' to close
               all remaining boxes and flush the pretty-printer.

                The behaviour of pretty-printing commands is unspecified if
               there is no opened pretty-printing box. Each box opened via one
               of the `open_' functions below must be closed using `close_box'
               for proper formatting. Otherwise, some of the material printed
               in the boxes may not be output, or may be formatted incorrectly.

                In case of interactive use, the system closes all opened boxes
               and flushes all pending text (as with the `print_newline'
               function) after each phrase. Each phrase is therefore executed
               in the initial state of the pretty-printer.

Boxes
=-=-=-

<<
  val open_box : int -> unit;;
>>
   open_box@`open_box'
                `open_box d' opens a new pretty-printing box with offset `d'.
               This box is the general purpose pretty-printing box. Material in
               this box is displayed ``horizontal or vertical'': break hints
               inside the box may lead to a new line, if there is no more room
               on the line to print the remainder of the box, or if a new line
               may lead to a new indentation (demonstrating the indentation of
               the box). When a new line is printed in the box, `d' is added to
               the current indentation.

<<
  val close_box : unit -> unit;;
>>
   close_box@`close_box'
                Close the most recently opened pretty-printing box.

Formatting functions
=-=-=-=-=-=-=-=-=-=-=

<<
  val print_string : string -> unit;;
>>
   print_string@`print_string'
                `print_string str' prints `str' in the current box.

<<
  val print_as : int -> string -> unit;;
>>
   print_as@`print_as'
                `print_as len str' prints `str' in the current box. The
               pretty-printer formats `str' as if it were of length `len'.

<<
  val print_int : int -> unit;;
>>
   print_int@`print_int'
                Print an integer in the current box.

<<
  val print_float : float -> unit;;
>>
   print_float@`print_float'
                Print a floating point number in the current box.

<<
  val print_char : char -> unit;;
>>
   print_char@`print_char'
                Print a character in the current box.

<<
  val print_bool : bool -> unit;;
>>
   print_bool@`print_bool'
                Print an boolean in the current box.

Break hints
=-=-=-=-=-=-

<<
  val print_space : unit -> unit;;
>>
   print_space@`print_space'
                `print_space ()' is used to separate items (typically to print
               a space between two words).  It indicates that the line may be
               split at this point. It either prints one space or splits the
               line. It is equivalent to `print_break 1 0'.

<<
  val print_cut : unit -> unit;;
>>
   print_cut@`print_cut'
                `print_cut ()' is used to mark a good break position. It
               indicates that the line may be split at this  point. It either
               prints nothing or splits the line. This allows line splitting at
               the current point, without printing spaces or adding
               indentation. It is equivalent to `print_break 0 0'.

<<
  val print_break : int -> int -> unit;;
>>
   print_break@`print_break'
                Insert a break hint in a pretty-printing box. `print_break
               nspaces offset' indicates that the line may be split (a newline
               character is printed) at this point, if the contents of the
               current box does not fit on one line. If the line is split at
               that point, `offset' is added to the current indentation. If the
               line is not split, `nspaces' spaces are printed.

<<
  val print_flush : unit -> unit;;
>>
   print_flush@`print_flush'
                Flush the pretty printer: all opened boxes are closed, and all
               pending text is displayed.

<<
  val print_newline : unit -> unit;;
>>
   print_newline@`print_newline'
                Equivalent to `print_flush' followed by a new line.

<<
  val force_newline : unit -> unit;;
>>
   force_newline@`force_newline'
                Force a newline in the current box. Not the normal way of
               pretty-printing, you should prefer break hints.

<<
  val print_if_newline : unit -> unit;;
>>
   print_if_newline@`print_if_newline'
                Execute the next formatting command if the preceding line has
               just been split. Otherwise, ignore the next formatting command.

Margin
=-=-=-=

<<
  val set_margin : int -> unit;;
>>
   set_margin@`set_margin'
                `set_margin d' sets the value of the right margin to `d' (in
               characters): this value is used to detect line overflows that
               leads to split lines. Nothing happens if `d' is smaller than 2
               or bigger than 999999999.

<<
  val get_margin : unit -> int;;
>>
   get_margin@`get_margin'
                Return the position of the right margin.

Maximum indentation limit
=-=-=-=-=-=-=-=-=-=-=-=-=-

<<
  val set_max_indent : int -> unit;;
>>
   set_max_indent@`set_max_indent'
                `set_max_indent d' sets the value of the maximum indentation
               limit to `d' (in characters): once this limit is reached, boxes
               are rejected to the left, if they do not fit on the current
               line. Nothing happens if `d' is smaller than 2 or bigger than
               999999999.

<<
  val get_max_indent : unit -> int;;
>>
   get_max_indent@`get_max_indent'
                Return the value of the maximum indentation limit (in
               characters).

Formatting depth: maximum number of boxes allowed before ellipsis
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

<<
  val set_max_boxes : int -> unit;;
>>
   set_max_boxes@`set_max_boxes'
                `set_max_boxes max' sets the maximum number of boxes
               simultaneously opened. Material inside boxes nested deeper is
               printed as an ellipsis (more precisely as the text returned by
               `get_ellipsis_text ()'). Nothing happens if `max' is not greater
               than 1.

<<
  val get_max_boxes : unit -> int;;
>>
   get_max_boxes@`get_max_boxes'
                Return the maximum number of boxes allowed before ellipsis.

<<
  val over_max_boxes : unit -> bool;;
>>
   over_max_boxes@`over_max_boxes'
                Test the maximum number of boxes allowed have already been
               opened.

Advanced formatting
=-=-=-=-=-=-=-=-=-=-

<<
  val open_hbox : unit -> unit;;
>>
   open_hbox@`open_hbox'
                `open_hbox ()' opens a new pretty-printing box. This box is
               ``horizontal'': the line is not split in this box (new lines may
               still occur inside boxes nested deeper).

<<
  val open_vbox : int -> unit;;
>>
   open_vbox@`open_vbox'
                `open_vbox d' opens a new pretty-printing box with offset `d'.
               This box is ``vertical'': every break hint inside this box leads
               to a new line. When a new line is printed in the box, `d' is
               added to the current indentation.

<<
  val open_hvbox : int -> unit;;
>>
   open_hvbox@`open_hvbox'
                `open_hvbox d' opens a new pretty-printing box with offset `d'.
                This box is ``horizontal-vertical'': it behaves as an
               ``horizontal'' box if it fits on a single line, otherwise it
               behaves as a ``vertical'' box. When a new line is printed in the
               box, `d' is added to the current indentation.

<<
  val open_hovbox : int -> unit;;
>>
   open_hovbox@`open_hovbox'
                `open_hovbox d' opens a new pretty-printing box with offset
               `d'.  This box is ``horizontal or vertical'': break hints inside
               this box may lead to a new line, if there is no more room on the
               line to print the remainder of the box. When a new line is
               printed in the box, `d' is added to the current indentation.

Tabulations
=-=-=-=-=-=-

<<
  val open_tbox : unit -> unit;;
>>
   open_tbox@`open_tbox'
                Open a tabulation box.

<<
  val close_tbox : unit -> unit;;
>>
   close_tbox@`close_tbox'
                Close the most recently opened tabulation box.

<<
  val print_tbreak : int -> int -> unit;;
>>
   print_tbreak@`print_tbreak'
                Break hint in a tabulation box. `print_tbreak spaces offset'
               moves the insertion point to the next tabulation (`spaces' being
               added to this position). Nothing occurs if insertion point is
               already on a tabulation mark. If there is no next tabulation on
               the line, then a newline is printed and the insertion point
               moves to the first tabulation of the box. If a new line is
               printed, `offset' is added to the current indentation.

<<
  val set_tab : unit -> unit;;
>>
   set_tab@`set_tab'
                Set a tabulation mark at the current insertion point.

<<
  val print_tab : unit -> unit;;
>>
   print_tab@`print_tab'
                `print_tab ()' is equivalent to `print_tbreak (0,0)'.

Ellipsis
=-=-=-=-=

<<
  val set_ellipsis_text : string -> unit;;
>>
   set_ellipsis_text@`set_ellipsis_text'
                Set the text of the ellipsis printed when too many boxes are
               opened (a single dot, `.', by default).

<<
  val get_ellipsis_text : unit -> string;;
>>
   get_ellipsis_text@`get_ellipsis_text'
                Return the text of the ellipsis.

Redirecting formatter output
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

<<
  val set_formatter_out_channel : out_channel -> unit;;
>>
   set_formatter_out_channel@`set_formatter_out_channel'
                Redirect the pretty-printer output to the given channel.

<<
  val set_formatter_output_functions :
        (string -> int -> int -> unit) -> (unit -> unit) -> unit;;
>>
   set_formatter_output_functions@`set_formatter_output_functions'
                `set_formatter_output_functions out flush' redirects the
               pretty-printer output to the functions `out' and `flush'. The
               `out' function performs the pretty-printer output. It is called
               with a string `s', a start position `p', and a number of
               characters `n'; it is supposed to output characters `p' to
               `p+n-1' of `s'. The `flush' function is called whenever the
               pretty-printer is flushed using `print_flush' or
               `print_newline'.

<<
  val get_formatter_output_functions :
          unit -> (string -> int -> int -> unit) * (unit -> unit);;
>>
   get_formatter_output_functions@`get_formatter_output_functions'
                Return the current output functions of the pretty-printer.

Changing the meaning of indentation and line breaking
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

<<
  val set_all_formatter_output_functions :
        (string -> int -> int -> unit) -> (unit -> unit) ->
        (unit -> unit) -> (int -> unit) -> unit;;
>>
   set_all_formatter_output_functions@`set_all_formatter_output_functions'
                `set_all_formatter_output_functions out flush outnewline
               outspace' redirects the pretty-printer output to the functions
               `out' and `flush' as described in
               `set_formatter_output_functions'. In addition, the
               pretty-printer function that outputs a newline is set to the
               function `outnewline' and the function that outputs indentation
               spaces is set to the function `outspace'. This way, you can
               change the meaning of indentation (which can be something else
               than just printing a space character) and the meaning of new
               lines opening (which can be connected to any other action needed
               by the application at hand). The two functions `outspace' and
               `outnewline' are normally connected to `out' and `flush':
               respective default values for `outspace' and `outnewline' are
               `out (String.make n ' ') 0 n' and `out "\n" 0 1'.

<<
  val get_all_formatter_output_functions : unit ->
          (string -> int -> int -> unit) * (unit -> unit) *
          (unit -> unit) * (int -> unit);;
>>
   get_all_formatter_output_functions@`get_all_formatter_output_functions'
                Return the current output functions of the pretty-printer,
               including line breaking and indentation functions.

Multiple formatted output
=-=-=-=-=-=-=-=-=-=-=-=-=-

<<
  type formatter;;
>>

                Abstract data type corresponding to a pretty-printer and all
               its machinery. Defining new pretty-printers permits the output
               of material in parallel on several channels. Parameters of the
               pretty-printer are local to the pretty-printer: margin, maximum
               indentation limit, maximum number of boxes simultaneously
               opened, ellipsis, and so on, are specific to each pretty-printer
               and may be fixed independently. Given an output channel `oc', a
               new formatter writing to that channel is obtained by calling
               `formatter_of_out_channel oc'. Alternatively the
               `make_formatter' function allocates a new formatter with
               explicit output and flushing functions (convenient to output
               material to strings for instance).

<<
  val formatter_of_out_channel : out_channel -> formatter;;
>>
   formatter_of_out_channel@`formatter_of_out_channel'
                `formatter_of_out_channel oc' returns a new formatter that
               writes to the corresponding channel `oc'.

<<
  val std_formatter : formatter;;
>>
   std_formatter@`std_formatter'
                The standard formatter used by the formatting functions above.
               It is defined as `formatter_of_out_channel stdout'.

<<
  val err_formatter : formatter;;
>>
   err_formatter@`err_formatter'
                A formatter to use with formatting functions below for output
               to standard error. It is defined as `formatter_of_out_channel
               stderr'.

<<
  val formatter_of_buffer : Buffer.t -> formatter;;
>>
   formatter_of_buffer@`formatter_of_buffer'
                `formatter_of_buffer b' returns a new formatter writing to
               buffer `b'. As usual, the formatter has to be flushed at the end
               of pretty printing, using `pp_print_flush' or
               `pp_print_newline', to display all the pending material. In this
               case the buffer is also flushed using `Buffer.flush'.

<<
  val stdbuf : Buffer.t;;
>>
   stdbuf@`stdbuf'
                The string buffer in which `str_formatter' writes.

<<
  val str_formatter : formatter;;
>>
   str_formatter@`str_formatter'
                A formatter to use with formatting functions below for output
               to the `stdbuf' string buffer.

<<
  val flush_str_formatter : unit -> string;;
>>
   flush_str_formatter@`flush_str_formatter'
                Returns the material printed with `str_formatter', flushes the
               formatter and reset the corresponding buffer. `str_formatter' is
               defined as `formatter_of_buffer stdbuf'.

<<
  val make_formatter :
          (string -> int -> int -> unit) -> (unit -> unit) -> formatter;;
>>
   make_formatter@`make_formatter'
                `make_formatter out flush' returns a new formatter that writes
               according to the output function `out', and the flushing
               function `flush'. Hence, a formatter to out channel `oc' is
               returned by `make_formatter (output oc) (fun () -> flush oc)'.

<<
  val pp_open_hbox : formatter -> unit -> unit;;
  val pp_open_vbox : formatter -> int -> unit;;
  val pp_open_hvbox : formatter -> int -> unit;;
  val pp_open_hovbox : formatter -> int -> unit;;
  val pp_open_box : formatter -> int -> unit;;
  val pp_close_box : formatter -> unit -> unit;;
  val pp_print_string : formatter -> string -> unit;;
  val pp_print_as : formatter -> int -> string -> unit;;
  val pp_print_int : formatter -> int -> unit;;
  val pp_print_float : formatter -> float -> unit;;
  val pp_print_char : formatter -> char -> unit;;
  val pp_print_bool : formatter -> bool -> unit;;
  val pp_print_break : formatter -> int -> int -> unit;;
  val pp_print_cut : formatter -> unit -> unit;;
  val pp_print_space : formatter -> unit -> unit;;
  val pp_force_newline : formatter -> unit -> unit;;
  val pp_print_flush : formatter -> unit -> unit;;
  val pp_print_newline : formatter -> unit -> unit;;
  val pp_print_if_newline : formatter -> unit -> unit;;
  val pp_open_tbox : formatter -> unit -> unit;;
  val pp_close_tbox : formatter -> unit -> unit;;
  val pp_print_tbreak : formatter -> int -> int -> unit;;
  val pp_set_tab : formatter -> unit -> unit;;
  val pp_print_tab : formatter -> unit -> unit;;
  val pp_set_margin : formatter -> int -> unit;;
  val pp_get_margin : formatter -> unit -> int;;
  val pp_set_max_indent : formatter -> int -> unit;;
  val pp_get_max_indent : formatter -> unit -> int;;
  val pp_set_max_boxes : formatter -> int -> unit;;
  val pp_get_max_boxes : formatter -> unit -> int;;
  val pp_over_max_boxes : formatter -> unit -> bool;;
  val pp_set_ellipsis_text : formatter -> string -> unit;;
  val pp_get_ellipsis_text : formatter -> unit -> string;;
  val pp_set_formatter_out_channel : formatter -> out_channel -> unit;;
  val pp_set_formatter_output_functions : formatter ->
          (string -> int -> int -> unit) -> (unit -> unit) -> unit;;
  val pp_get_formatter_output_functions :
          formatter -> unit -> (string -> int -> int -> unit) * (unit ->
unit);;
  val pp_set_all_formatter_output_functions : formatter ->
        (string -> int -> int -> unit) -> (unit -> unit) ->
        (unit -> unit) -> (int -> unit) -> unit;;
  val pp_get_all_formatter_output_functions : formatter -> unit ->
        (string -> int -> int -> unit) * (unit -> unit) *
        (unit -> unit) * (int -> unit);;
>>
   pp_open_hbox@`pp_open_hbox'pp_open_vbox@`pp_open_vbox'pp_open_hvbox@`pp_open
_hvbox'pp_open_hovbox@`pp_open_hovbox'pp_open_box@`pp_open_box'pp_close_box@`pp
_close_box'pp_print_string@`pp_print_string'pp_print_as@`pp_print_as'pp_print_i
nt@`pp_print_int'pp_print_float@`pp_print_float'pp_print_char@`pp_print_char'pp
_print_bool@`pp_print_bool'pp_print_break@`pp_print_break'pp_print_cut@`pp_prin
t_cut'pp_print_space@`pp_print_space'pp_force_newline@`pp_force_newline'pp_prin
t_flush@`pp_print_flush'pp_print_newline@`pp_print_newline'pp_print_if_newline@
`pp_print_if_newline'pp_open_tbox@`pp_open_tbox'pp_close_tbox@`pp_close_tbox'pp
_print_tbreak@`pp_print_tbreak'pp_set_tab@`pp_set_tab'pp_print_tab@`pp_print_ta
b'pp_set_margin@`pp_set_margin'pp_get_margin@`pp_get_margin'pp_set_max_indent@`
pp_set_max_indent'pp_get_max_indent@`pp_get_max_indent'pp_set_max_boxes@`pp_set
_max_boxes'pp_get_max_boxes@`pp_get_max_boxes'pp_over_max_boxes@`pp_over_max_bo
xes'pp_set_ellipsis_text@`pp_set_ellipsis_text'pp_get_ellipsis_text@`pp_get_ell
ipsis_text'pp_set_formatter_out_channel@`pp_set_formatter_out_channel'pp_set_fo
rmatter_output_functions@`pp_set_formatter_output_functions'pp_get_formatter_ou
tput_functions@`pp_get_formatter_output_functions'pp_set_all_formatter_output_f
unctions@`pp_set_all_formatter_output_functions'pp_get_all_formatter_output_fun
ctions@`pp_get_all_formatter_output_functions'
                The basic functions to use with formatters. These functions are
               the basic ones: usual functions operating on the standard
               formatter are defined via partial evaluation of these
               primitives. For instance, `print_string' is equal to
               `pp_print_string std_formatter'.

<<
  val fprintf : formatter -> ('a, formatter, unit) format -> 'a;;
>>
   fprintf@`fprintf'
                `fprintf ff format arg1 ... argN' formats the arguments `arg1'
               to `argN' according to the format string `format', and outputs
               the resulting string on the formatter `ff'. The format is a
               character string which contains three types of objects: plain
               characters and conversion specifications as specified in the
               `printf' module, and pretty-printing indications. The
               pretty-printing indication characters are introduced by a `@'
               character, and their meanings are:
               `@[': open a pretty-printing box. The type and offset of the box
               may be optionally specified with the following syntax: the `<'
               character, followed by an optional box type indication, then an
               optional integer offset, and the closing `>' character.  Box
               type is one of `h', `v', `hv', `b', or `hov', which stand
               respectively for an horizontal box, a vertical box, an
               ``horizontal-vertical'' box, or an ``horizontal or vertical''
               box (`b' standing for an ``horizontal or vertical'' box
               demonstrating indentation and `hov' standing for a
               regular``horizontal or vertical'' box).  For instance, `@[<hov
               2>' opens an ``horizontal or vertical'' box with indentation 2.
               `@]': close the most recently opened pretty-printing box.
               `@,': output a good break as with `print_cut ()'.
               `@ ': output a space, as with `print_space ()'.
               `@\n': force a newline, as with `force_newline ()'.
               `@;': output a good break as with `print_break'. The `nspaces'
               and `offset' parameters of the break may be optionally specified
               with the following syntax:  the `<' character, followed by an
               integer `nspaces' value, then an integer offset, and a closing
               `>' character.
               `@?': flush the pretty printer as with `print_flush ()'.
               `@.': flush the pretty printer and output a new line, as with
               `print_newline ()'.
               `@<n>': print the following item as if it were of length `n'.
               Hence, `printf "@<0>%s" arg' is equivalent to `print_as 0 arg'.
               If `@<n>' is not followed by a conversion specification, then
               the following character of the format is printed as if it were
               of length `n'.
               `@@': print a plain `@' character.Example: `printf "@[%s@ %d@]"
               "x =" 1' is equivalent to  `open_box (); print_string "x =";
               print_space (); print_int 1; close_box ()'. It prints `x = 1'
               within a pretty-printing box.

<<
  val bprintf: Buffer.t -> ('a, formatter, unit) format -> 'a;;
>>
   bprintf@`bprintf'
                Same as `fprintf', but instead of printing on a formatter,
               writes into the buffer argument.

<<
  val printf : ('a, formatter, unit) format -> 'a;;
>>
   printf@`printf'
                Same as `fprintf', but output on `std_formatter'.

<<
  val eprintf: ('a, formatter, unit) format -> 'a;;
>>
   eprintf@`eprintf'
                Same as `fprintf', but output on `err_formatter'.

<<
  val sprintf: ('a, unit, string) format -> 'a;;
>>
   sprintf@`sprintf'
                Same as `printf', but instead of printing on a formatter,
               return a string containing the result of formatting the
               arguments.