-- File:	PCollection_HDataMap.cdl
-- Created:	Wed Feb 19 14:24:56 1992
-- Author:	Jean Pierre TIRAULT
--		<jpt@topsn1>
-- Revised:	Thu Jan  7 17:26:12 1993
-- By     :	Mireille MERCIEN
--		<mip@sdsun4>
---Copyright:	 Matra Datavision 1993


generic class HDataMap from PCollection  (Key as Storable; 
                                     Item as Storable;
                                     FH as Hash(Key) )
inherits Persistent

 	---Purpose: A map is a Collection of bindings
	-- between two objects. One is considered as
	-- the key and a hash code value must be 
	-- computed for it.


raises  MultiplyDefined from Standard,
        NoMoreObject    from Standard,
        NoSuchObject    from Standard
        


  
    class MapNode inherits PManaged
    	---Purpose: This class is used in the implementation of Map class.
     is
     
        Create( aKey : Key ; anItem : Item ; aNext : MapNode)
	    returns mutable MapNode from PCollection;

	GetKey (me) returns any Key is static;
        ---Level: Internal
	---Purpose: Returns myKey

    	Value(me) returns any Item is static;
        ---Level: Internal
	---Purpose: Returns myItem.
	
    	Next(me) returns mutable MapNode is static;
        ---Level: Internal
	    ---Purpose: Returns myNext.

	SetKey (me : mutable ; aKey : Key) is static;
        ---Level: Internal
	---Purpose: Modifies myKey.

    	SetValue( me : mutable; anItem: Item) is static;
            ---Level: Internal
	    ---Purpose: Modifies myItem.

    	SetNext( me : mutable; aNode: MapNode) is static;
            ---Level: Internal
	    ---Purpose: Modifies myNext.

     	ShallowCopy(me) returns mutable like me 
            	is redefined;
            ---Level: Internal
            ---Purpose: ShallowCopy redefinition
	    ---C++: function call

     	ShallowDump (me; s: in out OStream) 
            	is redefined;
            ---Level: Internal  
	    ---Purpose: ShallowDump redefinition
    	    ---C++: function call

    fields

        myKey      : Key;
	myItem     : Item;
	myNext     : MapNode;

    end;
	
    class Array instantiates HArray1 from PCollection(MapNode);
	
    class MapIterator

    raises NoMoreObject from Standard, 
           NoSuchObject from Standard
    is
    	---Purpose: This class provides to iterate on a Map from the
    	-- first bucket entry to the last one in the table;
    	-- Going through the associated list for each bucket entry.
                    
    	Create( aMap: HDataMap)
	    ---Purpose: Creates an iterator on <aMap> .
    	    returns MapIterator;

    	More( me)
            ---Level: Public
	    ---Purpose: Returns True if there is still an element to be read.
	    returns Boolean from Standard;
	    
    	Next( me: in out) raises NoMoreObject from Standard;
            ---Level: Public
	    ---Purpose: Goes to next element of <me>.
    
    	Value( me)
            ---Level: Public
    	    returns any Item
    	    raises NoSuchObject from Standard;
	    
    	GetKey( me)
            ---Level: Public
    	    returns Key
    	    raises NoSuchObject from Standard;
	    
    fields
        Buckets     : Array;
    	NbBuck      : Integer;
    	Index       : Integer;
	Node        : MapNode;
        HasMore     : Boolean;
    end;

is	
	Create(NbBuckets : Integer ; F : FH) returns mutable HDataMap;
		---Purpose: Creation of a map of NbBuckets entries.
		-- the table is empty.
                -- If NbBuckets eq. 0 an exception will be raised.
                    
	NbBuckets(me) returns Integer from Standard;
                ---Level: Public
		---Purpose: Returns the number of entries in the table.

	IsEmpty(me) returns Boolean from Standard;
                ---Level: Public
		---Purpose:  Returns true if the table is empty.

	Extent(me) returns Integer from Standard ;
                ---Level: Public
		---Purpose:  Returns the number of elements in the table.
		---Example: if me is the hash table ((a x)(b y)(c z)) Extent
		-- returns 3

	IsBound(me; K : Key) returns Boolean;
                ---Level: Public
		---Purpose: Returns True if an element is bounded to K

	Find(me; K : Key) returns  any Item raises NoSuchObject;
                ---Level: Public
		---Purpose: Returns the element bounded to K.
		-- Raises an exception if the binding does not exist.
		---Example: before
		--   me = ((a x)(b y)(c z)) , K = b
		-- returns y

	Clear(me:mutable);
                ---Level: Public
		---Purpose: Removes all the element in the table.
		---Example: before
		--   me = ((a x)(b y)(c z))
		-- after
		--   me = ()

	Bind(me:mutable; K : Key; T : Item) 
    	    raises MultiplyDefined;
                ---Level: Public
		---Purpose: Creates a binding between a key K and an item T.
		-- Raises an exception if the binding already exists.
		---Example: before
		--   me = ((a x)(b y)) , K = c , T = z
		-- after
		--   me = ((a x)(b y)(c z))

	Rebind(me:mutable; K : Key; T : Item) raises NoSuchObject;
                ---Level: Public
		---Purpose: Replaces the object binded to the key K by T.
		-- Raises an exception if the binding does not exist.
		---Example: before
		--   me = ((a x)(b y)) , K = b , T = z
		-- after
		--   me = ((a x)(b z))

	Unbind(me:mutable; K : Key) raises NoSuchObject;
                ---Level: Public
		---Purpose:  Removes the binding keyed by K.
		-- Raises an exception if the binding does not exist.
		---Example: before
		--   me = ((a x)(b y)(c z)) , K = b
		-- after
		--   me = ((a x)(c z))
	
     	ShallowCopy(me) returns mutable like me 
            	is redefined;
                ---Level: Advanced
	    	---Purpose: ShallowCopy redefinition
	    	---C++: function call


     	ShallowDump (me; s: in out OStream) 
            	is redefined;
                ---Level: Advanced
	    	---Purpose: ShallowDump redefinition
    	    	---C++: function call


        GetArray (me) returns Array is private;
                ---Level: Internal
	    	---Purpose :Returns the field Buckets associated to the object.
	    	---C++: inline

        GetFH (me) returns FH is private;
                ---Level: Internal
	    	---Purpose :Returns the field Hash associated to the object.
	    	---C++: inline

fields 
	Buckets : Array;
	Hash    : FH;

friends class MapIterator from PCollection

end HDataMap;