(* bitlist.mli *)
(* 15-411 *)
(* by Roland Flury *)
(* @version $Id: bitlist.mli,v 1.1 2004/11/01 09:23:14 ajo Exp $ *)

(* Description:
   Implements a module that provieds bitLists
   BitLists are mutable objects, i.e. the object itself does not get
   copied all the time, but is just like an object pointed to by a pointer. 
   
   Available functions
   -------------------
   - Create a new Bit_list with at least n entries
   - set a bit to 1 (bit specified with the place in the bit-list)
   - set a bit to 0 (bit specified with the place in the bit-list)
   - Read content of bit (bit specified with the place in the bit-list)
   - AND / OR / NOT / XOR two BitArrays;
   - Iterate over a bitList
*)

type bitList_t = int array ref

(* Creates a new BitList and returns a reference to it.
 * Initilizes all entries to 0 (false).
 * The size of the bitList is **at least** as big as specified *)
val newBitList : int -> bitList_t
    
(* Set the bit at offset n to true == 1, first element has offset 0 
 * Raises Invalid_argument if n is out of range *)
val setBit : bitList_t -> int -> unit
    
(* Set the bit at offset n to false == 0, first element has offset 0 
 * Raises Invalid_argument if n is out of range *)
val resetBit : bitList_t -> int -> unit

(* Reads the bit at offset n and returns either true (for 1) or false (for 0) 
 * Raises Invalid_argument if n is out of range *)
val getBit : bitList_t -> int -> bool

(* Returns the maximum number of bits storable in a bitList
 * => is at least as big as indicated in the constructor newBitList *)
val getLength : bitList_t -> int

(* Sets all entries to 0 (false) *)
val nullBitList : bitList_t -> unit

(* Copies the content of a BitList to a second BitList 
 * Raises Invalid_argument if length(toL) < length(fromL) *)
val copyBitList : bitList_t -> bitList_t -> unit

(* Makes a copy of a BitList and returns a new BitList *)
val copyBitListNew : bitList_t -> bitList_t

(* Returns a list of temps that are set in the bit list *)
val getTempList : bitList_t -> (int -> 'a) -> 'a list

(* Returns true if the two bitlists are equal *)
val isEqual : bitList_t -> bitList_t -> bool

(***********************************************************************)
(* AND OR XOR NOT; write the result in a new bitList *)
(***********************************************************************)
val andBLnew : bitList_t -> bitList_t -> bitList_t
val orBLnew : bitList_t -> bitList_t -> bitList_t 
val xorBLnew : bitList_t -> bitList_t -> bitList_t
val notBLnew : bitList_t -> bitList_t

(***********************************************************************)
(* AND OR XOR NOT; write the result in the second operand *)
(***********************************************************************)
val andBLto2 : bitList_t -> bitList_t -> unit
val orBLto2 : bitList_t -> bitList_t -> unit 
val xorBLto2 : bitList_t -> bitList_t -> unit
val notBLto1 : bitList_t -> unit

(***********************************************************************)
(* Iterators *)
(***********************************************************************)

(* Iterate over set bits in a bitlist *)
val iterTrue : (int -> unit) -> bitList_t -> unit

(* Iterate over all bits in a bitlist *)
val iter : (int -> bool -> unit) -> bitList_t -> unit

(* Find the first set bit, returns -1 if none was found *)
val findSet : bitList_t -> int

(* Executes the given function for every offset that is set to true *)
val fold : ('a -> int -> 'a) -> 'a -> bitList_t -> 'a