-- $Date: 2003/12/22 13:28:19 $
-- $Revision: 1.6 $
-- $Author: jcrocholl $

with Ada.Strings.Unbounded; use Ada.Strings.Unbounded;
with Hash_Tables;

generic

   -- Generic type of the items to be stored.
   --
   -- The key type for this package is String.
   type Item_Type is private;

package String_Hash_Tables is

   -- Calculate a hash code from an Unbounded_String.
   function Hash
     (Key : in Unbounded_String-- Calculate hash of this key.
      Max : in Positive)         -- Maximum result value.
     return Positive;            -- Number in the range from 1 to Max.

   -- Internal package: instance of Hash_Tables with Unbounded_String
   -- as the Key_Type. All String functions are then wrapped to this
   -- package.
   package US_Hash_Tables is
     new Hash_Tables(Unbounded_String, Item_Type, Hash, "=");

   -- Instance of a hash table.
   --
   -- No need to call a constructor. Uninitialized hash tables behave
   -- like regular empty ones.
   subtype Hash_Table is US_Hash_Tables.Hash_Table;

   -- The given key already exists in the hash table.
   --
   -- Raised by Put(Hash_Table, Key_Type, Item_Type).
   Key_Exists : exception
     renames US_Hash_Tables.Key_Exists;

   -- Check for available space in the table, grow if necessary, then
   -- insert the key item pair into the table.
   --
   -- Raises Key_Exists if the key is already in use.
   procedure Put
     (Table : in out Hash_Table-- Add pair to this hash table.
      Key   : in String;         -- The new key to be added.
      Item  : in Item_Type);     -- The new item to be added.

   -- Retrieve an item from the table.
   --
   -- Output parameter Found tells you whether the item was found in
   -- the table.
   procedure Get
     (Table : in Hash_Table-- Get value from this hash table.
      Key   : in String;     -- Look up this key.
      Item  : out Item_Type-- The item associated with the key.
      Found : out Boolean);  -- Was the item actually found?

   -- The given key was not found in the hash table.
   --
   -- Raised by Get(Hash_Table, Key_Type).
   Key_Not_Found : exception
     renames US_Hash_Tables.Key_Not_Found;

   -- Retrieve an item from the table.
   --
   -- Raises Key_Not_Found if the key is not in the table.
   function Get
     (Table : in Hash_Table-- Get value from this hash table.
      Key   : in String)     -- Look up this key.
     return Item_Type;       -- The item associated with the key.

   -- Iterate over the items in the table.
   --
   -- You should start with an Index of 0 and stop iterating as soon
   -- as Index is 0 again.
   procedure Get_Next
     (Table : in Hash_Table;        -- Get pair from this hash table.
      Index : in out Natural;       -- Iteration pointer to the current field.
      Key   : out Unbounded_String-- The key at the current field.
      Item  : out Item_Type)        -- The item at the current field.
     renames US_Hash_Tables.Get_Next;

   -- Print a visual representation of the hash table's usage.
   --
   -- Empty fields are represented by a '-' character, used fields by
   -- '#'.
   procedure Print_Usage
     (Table : in Hash_Table-- Print usage of this hash table.
     renames US_Hash_Tables.Print_Usage;

end String_Hash_Tables;