-- $Date: 2003/12/28 01:21:22 $
-- $Revision: 1.5 $
-- $Author: jcrocholl $

generic

   -- Type for items in the heap.
   type Content_Type is private;

   -- Useful for debugging the heap.
   with function To_String
     (Item : in Content_Type)
     return String
     is <>;

   -- Comparing items. If this function returns true, A will be
   -- considered lighter than B and will be moved up in the heap.
   -- The lightest element will always be extracted first.
   with function "<"
     (A, B : in Content_Type-- Left and right operands.
     return Boolean           -- Result of comparison.
     is <>;

-- An efficiently sorting dynamically sized data structure.
package Heaps is

   -- Type for instances. Doesn't need to be initialized. Unitialized
   -- heaps behave like regular empty ones.
   type Heap is private;

   -- An empty heap if you ever explicitly need one.
   Empty_Heap : constant Heap;

   -----------------------
   -- Heap size management
   -----------------------

   -- Grow or shrink a heap. If the new size is smaller than the
   -- number of items in the heap, some items will be cut off at the
   -- end without warning.
   procedure Resize
     (This     : in out Heap;  -- Resize this heap.
      New_Size : in Positive); -- New size of the heap.

   -- Explicitly empty a heap and release associated memory.
   procedure Deallocate
     (This : in out Heap); -- Empty this heap.

   --------------------
   -- State information
   --------------------

   -- How many items in the heap?
   function Count
     (This : in Heap-- Read count from this heap.
     return Natural;  -- Item count of this heap.

   -- Print the heap's contents.
   procedure Debug
     (This : in Heap); -- Debug this heap.

   ----------------------
   -- Writing and reading
   ----------------------

   -- Insert an item into the heap.
   procedure Insert
     (This : in out Heap;      -- Insert into this heap.
      Item : in Content_Type); -- The item to insert.

   -- Extract the lightest item from the heap.
   function Extract
     (This : in Heap)     -- Extract from this heap.
     return Content_Type-- The lightest item.

private

   -- Variable size array.
   type Content_Type_Array is array(Positive range <>) of Content_Type;

   type Heap_Record(Size : Positive) is record
      Count : Natural := 0;
      Items : Content_Type_Array(1 .. Size);
   end record;

   -- Finally, the definition of a heap.
   type Heap is access Heap_Record;

   Empty_Heap : constant Heap := null;

end Heaps;