-- $Date: 2004/01/27 12:03:47 $
-- $Revision: 1.3 $
-- $Author: jcrocholl $

-- A constrained string type. Limited type minimizes memory
-- leaks. Useful for storage in arrays, lists and hash tables.
-- Does not need controlled types, unlike Unbounded_Strings.
package Strings is

   -- Constrained string type.
   type String_Access is limited private;

   -- Create string access. Free previous value if applicable.
   procedure To_String_Access
     (This   : in String;             -- Convert this string.
      Result : in out String_Access); -- Return result here.

   -- Create a new string access.
   function To_String_Access
     (This : in String)    -- Convert this string.
     return String_Access-- Return result here.

   -- Deallocate storage for this string access, if allocated.
   procedure Free
     (This : in out String_Access); -- Deallocate this string access.

   -- Check if a string access is unallocated.
   function Is_Null
     (This : in String_Access-- Check this string access.
     return Boolean;           -- True if not allocated.

   -- Read a string value from a string access.
   function To_String
     (This : in String_Access-- Convert this string access.
     return String;            -- The resulting string value.

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

   -- Compare two string values, not their pointers.
   function Equal
     (A, B : in String_Access-- Compare these string values.
     return Boolean;           -- True if strings are equal.

   -- Get allocation statistics.
   function Statistics
     return String-- The statistics report.

   ----------------
   -- String arrays
   ----------------

   -- Unconstrained array of strings.
   type String_Array is array(Positive range <>) of String_Access;

private

   -- Limited private declaration.
   type String_Access is access String;

end Strings;