documented Iheap and added Iheap.clear

common/iheap.ml

@@ -13,7 +13,7 @@
 
 type t = {heap : int Vec.t; indices : int Vec.t }
 
-let dummy = -100
+let dummy = 0
 
 let init sz =
   { heap    =  Vec.init sz (fun i -> i) dummy;
@@ -96,6 +96,11 @@ let size s = Vec.size s.heap
 
 let is_empty s = Vec.is_empty s.heap
 
+let clear {heap; indices} =
+  Vec.clear heap;
+  Vec.clear indices;
+  ()
+
 let insert cmp s n =
   if not (in_heap s n) then
     begin
@@ -123,6 +128,7 @@ let update cmp s n =
 *)
 
 let remove_min cmp ({heap=heap; indices=indices} as s) =
+  if Vec.size heap=0 then raise Not_found;
   let x = Vec.get heap 0 in
   Vec.set heap 0 (Vec.last heap); (*heap.last()*)
   Vec.set indices (Vec.get heap 0) 0;

common/iheap.mli

@@ -12,15 +12,44 @@
 (**************************************************************************)
 
 type t
+(** Heap of integers, whose priority is increased or decreased
+    incrementally (see {!decrease} for instance) *)
 
 val init : int -> t
+(** Create a heap with the given number of values inside.
+    [init len] contains integers from [0] to [len-1]. *)
+
 val in_heap : t -> int -> bool
+(** [in_heap h x] returns [true] iff [x] is among the integers that belong to
+    the heap. *)
+
 val decrease : (int -> int -> bool) -> t -> int -> unit
+(** [decrease cmp h x] decreases the value associated to [x] within [h],
+    according to the comparison function [cmp] *)
+
 (*val increase : (int -> int -> bool) -> t -> int -> unit*)
+
 val size : t -> int
+(** Number of integers within the heap *)
+
 val is_empty : t -> bool
+
+val clear : t -> unit
+(** Clear the content of the heap *)
+
 val insert : (int -> int -> bool) -> t -> int -> unit
+(** Insert a new integer into the heap, according to the given comparison *)
+
 val grow_to_by_double: t -> int -> unit
+(** Augment the internal capacity of the heap until it reaches at
+    least the given integer *)
+
 (*val update : (int -> int -> bool) -> t -> int -> unit*)
+
 val remove_min : (int -> int -> bool) -> t -> int
+(** Remove and return the integer that has the lowest value from the heap
+    @raise Not_found if the heap is empty *)
+
 val filter : t -> (int -> bool) -> (int -> int -> bool) -> unit
+(** Filter out values that don't satisfy the predicate. A comparison
+    function is used to re-order the heap *)