(* $Header: /home/pauillac/formel1/fpottier/cvs/laurel/zone.mli,v 1.6 2000/03/01 14:20:44 fpottier Exp $ *)

(* This module defines zones. These objects define an immutable zone in a larger string. They come equipped with a
   mutable ``read head'', which allows easily reading a sequence of elements from a zone. *)

type t

(* This function creates a zone out of a string. The zone spans the whole string. Its read head is initially located
   at the beginning of the zone. *)

val create: string -> t

(* This exception is raised when attempting to read past the end of a zone. *)

exception EOZ

(* This function reads an unsigned 8-bit integer at the read head's current position. After reading, the read head
   advances by one byte. *)

val u1: t -> int

(* This function reads a signed 8-bit integer at the read head's current position. After reading, the read head
   advances by one byte. *)

val s1: t -> int

(* This function reads an unsigned 16-bit integer, in big-endian order, at the read head's current position. After
   reading, the read head advances by two bytes. *)

val u2: t -> int

(* This function reads a signed 16-bit integer, in big-endian order, at the read head's current position. After
   reading, the read head advances by two bytes. *)

val s2: t -> int

(* This function reads an unsigned 16-bit integer, in big-endian order, at the read head's current position. The
   read head does not advance. *)

val peek2: t -> int

(* This function reads a signed 32-bit integer, in big-endian order, at the read head's current position. After
   reading, the read head advances by four bytes. TEMPORARY Because O'Caml integers are signed 31-bit, the result
   will be incorrect if the integer stored in the zone has more than 30 significant bits. *)

val s4: t -> int

(* This function reads a sub-zone of length [length] at the read head's current position. After reading, the
   read head advances by [length] bytes. The newly created zone uses the same data buffer as its parent zone.
   Its read head is initially located at the beginning of the sub-zone. *)

val sub: t -> int -> t

(* This function converts a zone into a string. It is the sub-string of the original buffer string covered by
   the zone. The zone's read head position is irrelevant, and unaffected. *)

val string: t -> string

(* This function reads in a ``table'' consisting of an element count (to be read by [rc]), followed by as many
   (possibly variable-length) elements. [rc] should typically be [u1] or [u2], depending on whether the element count
   is stored using one or two bytes. The [element] auxiliary function is invoked to read each element. It finds the
   read head positioned at the beginning of the element, and must leave it at the end of the element. The table is
   returned as a list, where the first element found in the zone appears first. The read head is advanced to the end
   of the table. *)

val table: t -> (t -> int) -> (t -> 'a) -> 'a list

(* This function reads in a ``table'' consisting of an undetermined number of (possibly variable-length) elements. The
   end of the table is deemed to coincide with the end of the zone. The [element] auxiliary function is invoked to
   read each element. It finds the read head positioned at the beginning of the element, and must leave it at the end
   of the element. The table is returned as a list, where the first element found in the zone appears first. The read
   head is advanced to the end of the table. *)

val undetermined_table: t -> (t -> 'a) -> 'a list

(* This function reads in a ``table'' consisting of an undetermined number of (possibly variable-length) elements. The
   end of the table is deemed to coincide with the end of the zone. The [element] auxiliary function is invoked to
   read each element. It finds the read head positioned at the beginning of the element, and must leave it at the end
   of the element. The table is returned as a hash table which maps zone offsets to elements. The zone's read head is
   advanced to the end of the table. *)

val hash_table: t -> (t -> 'a) -> (int, 'a) Hashtbl.t

(* This function reads in a ``Pascal'' string, i.e. a string prefixed with its length in bytes. The length field is
   to be read by [rc]. The read head is advanced to the end of the string. *)

val pascal: t -> (t -> int) -> string

(* This function returns the zone's current read head position. *)

val head: t -> int

(* This function sets the zone's read head position. *)

val seek: t -> int -> unit

(* This function returns a zone's length. *)

val length: t -> int