[occt.git] / src / TCollection / TCollection_DataMap.cdl

-- Created on: 1993-01-08
-- Created by: Remi LEQUETTE
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

generic class DataMap from TCollection 
   (TheKey    as any;
    TheItem   as any;
    Hasher as any) -- as MapHasher(TheKey)
inherits BasicMap from TCollection

	---Purpose: The DataMap is a Map to store keys with associated
	-- Items.An entry of a DataMap is composed of both the key and the item.
	-- The DataMap can be seen as an extended array where
	-- the Keys  are the   indices.  For this reason  the
	-- operator () is defined on DataMap to fetch an Item
	-- from a Key. So the following syntax can be used :
	-- 
	-- anItem = aMap(aKey);
	-- aMap(aKey) = anItem;
	-- 
	-- This analogy has its  limit.   aMap(aKey) = anItem
	-- can  be done only  if aKey was previously bound to
	-- an item in the map.
    	-- DataMap is a generic class which depends on three parameters:
    	-- -   Key is the type of key for an entry in the map,
    	-- -   Item is the type of element associated with a key in the   map,
    	-- -   Hasher is the type of hasher on keys.
    	-- Use a DataMapIterator iterator to explore a DataMap map.
    	-- Notes:
    	-- -   An iterator class is automatically instantiated from the
    	--   TCollection_DataMapIterator generic class at the
    	--   time of instantiation of a DataMap map.
    	-- -   TCollection_MapHasher class describes the
    	--   functions required for a Hasher object.
raises
    DomainError  from Standard,
    NoSuchObject from Standard

    class DataMapNode from TCollection 
    inherits MapNode from TCollection 
     
     
    
    uses MapNodePtr from TCollection
    is
      Create(K : TheKey; I : TheItem; n : MapNodePtr from TCollection) returns DataMapNode from TCollection;
      --- Purpose: Constructs a DataMap with NbBuckets (defaulted to 1) buckets.
      -- Note that the map will be automatically redimensioned
      -- during its use if the number of entries becomes too large.
      -- Use:
      -- -   the function Bind to add an entry (key, item) in the map,
      -- -   operator() to read an item from a key, or to assign a
      --  new value to this item,
      -- -   the function UnBind to remove an entry (key, item) from the map,
      -- -   and a map iterator to explore the map.
      ---C++: inline

      Key(me) returns TheKey;
      ---C++: return &
      ---C++: inline

      Value(me) returns TheItem;
      ---C++: return &
      ---C++: inline

    fields  
    	myKey : TheKey;
    	myValue : TheItem;
    end;
    
    class DataMapIterator inherits BasicMapIterator from TCollection
	---Purpose: Functions used for iterating the contents of a DataMap
    	-- Note: an iterator class is automatically instantiated from
    	-- this generic class at the time of instantiation of a DataMap.
    	-- Warning
    	-- -   A map is a non-ordered data structure. The order in
    	--   which entries of a map are explored by the iterator
    	--   depends on its contents, and change when the map is edited.
    	-- -   It is not recommended to modify the contents of a map
    	--   during iteration: the result is unpredictable.
 
    raises NoSuchObject from Standard	
    is
       	Create returns DataMapIterator from TCollection;
	    ---Purpose: Creates an undefined Iterator (empty); use the function Initialize to define the map to explore.
	
	Create (aMap : DataMap from TCollection) 
    	returns DataMapIterator from TCollection;
	    ---Purpose: Creates an Iterator on the map <aMap>.
	
	Initialize(me : in out; aMap : DataMap from TCollection)
	    ---Level: Public
	    ---Purpose: Sets, or resets the Iterator in the map <aMap>.
	is static;
	
	Key(me) returns any TheKey
	    ---Purpose: Returns the current Key. An error is raised if
	    -- the iterator is empty (More returns False).
    	    -- Note: Key is the type of key for an entry in the explored DataMap map.
    	    -- Exceptions
    	    -- Standard_NoSuchObject if this iterator is empty (i.e.
    	    -- when the function More returns false).
	    ---C++: return const &
	raises
	    NoSuchObject from Standard
	is static;
	
	Value(me) returns any TheItem
	    ---Purpose: Returns the item of the current entry in the map for this iterator.
    	    -- Note: Item is the type of element bound to a key in the explored DataMap map.
    	    -- Exceptions
    	    -- Standard_NoSuchObject if this iterator is empty (i.e.
    	    -- when the function More returns false)
	    ---C++: return const &
	raises
	    NoSuchObject from Standard
	is static;

    end DataMapIterator from TCollection;

is
    Create(NbBuckets : Integer = 1) returns DataMap from TCollection;
	---Purpose: Creates   a DataMap with  <NbBuckets> buckets. Without
	-- arguments the map is automatically dimensioned.
    

    Create(Other : DataMap from TCollection) returns DataMap from TCollection
	---Purpose: As  copying  Map  is an expensive  operation it is
	-- incorrect  to  do  it implicitly. This constructor is private and 
	-- will raise an error if the Map is not empty. 
	-- To copy the content of a DataMap use the Assign method (operator =).
    raises DomainError from Standard
    is private;
    
    Assign(me : in out; Other : DataMap from TCollection) 
    returns DataMap from TCollection
	---Purpose: Copies the contents of the map Other into this map.
    	-- Note that this method is an alias of operator =.
	---C++: alias operator =
	---C++: return & 
    is static;
    
    ReSize(me : in out; NbBuckets : Integer)
	---Level: Public
	---Purpose: Changes the  number    of  buckets of  <me>  to be
	-- <NbBuckets>. The keys  already  stored in  the map are kept.
    is static;
    
    Clear(me : in out)
	---Purpose: Removes all keys in the map.
	---C++: alias ~
    is static;
    
    Bind(me : in out; K : TheKey; I : TheItem) returns Boolean
	---Purpose: Adds the Key <K> to  the Map <me>  with  the  Item
	-- <I>.  Returns True  if the Key  was not already in
	-- the  Map.  If the  Key was already in the  Map the
	-- Item in the Map is replaced.
    is static;

    IsBound(me; K : TheKey) returns Boolean
	---Purpose: Returns True if the key <K>  is stored  in the map <me>. 
    is static;
    
    UnBind(me : in out; K : TheKey) returns Boolean
	---Purpose: Removes the Key <K> from the  map. Returns True if
	-- the Key was in the Map.
    	--   Returns false if the key K was not in this map.
        is static;
    
    Find(me; K : TheKey) returns any TheItem
	---Level: Public
	---Purpose: Returns  the Item stored  with the Key  <K> in the Map. 
        -- Trigger: An exception is raised when <K> is not in the map.
    raises NoSuchObject from Standard  
	---C++: alias operator()
	---C++: return const &
    is static;
    
    ChangeFind(me : in out; K : TheKey) returns any TheItem
	---Level: Public
	---Purpose: Returns the  Item stored with  the Key  <K> in the
	-- Map. This Item can be   modified with  the  syntax
	-- aMap(K) = newItem; 
        --  Trigger: An exception is raised when <K> is not in the map.
	---C++: alias operator()
	---C++: return &
    raises NoSuchObject from Standard 
    is static;
     
--modified by NIZNHY-PKV Tue Jul 05 09:57:10 2011f 
     Find1(me; K : TheKey) 
    	returns Address from Standard;	
	---Purpose: Returns the address of Item of the key <K>  
        -- or NULL if K is not in the map. 
     ChangeFind1(me:out; K : TheKey) 
    	returns Address from Standard;	
	---Purpose: Returns the address of Item of the key <K>  
        -- or NULL if K is not in the map. 
--modified by NIZNHY-PKV Tue Jul 05 09:57:14 2011t  

end DataMap;
Commit	Line	Data
b311480e	1	-- Created on: 1993-01-08
	2	-- Created by: Remi LEQUETTE
	3	-- Copyright (c) 1993-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
d5f74e42	8	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	9	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	10	-- by the Free Software Foundation, with special exception defined in the file
	11	-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
	12	-- distribution for complete text of the license and disclaimer of any warranty.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	generic class DataMap from TCollection
	18	(TheKey as any;
	19	TheItem as any;
	20	Hasher as any) -- as MapHasher(TheKey)
	21	inherits BasicMap from TCollection
	22
	23	---Purpose: The DataMap is a Map to store keys with associated
	24	-- Items.An entry of a DataMap is composed of both the key and the item.
	25	-- The DataMap can be seen as an extended array where
	26	-- the Keys are the indices. For this reason the
	27	-- operator () is defined on DataMap to fetch an Item
	28	-- from a Key. So the following syntax can be used :
	29	--
	30	-- anItem = aMap(aKey);
	31	-- aMap(aKey) = anItem;
	32	--
	33	-- This analogy has its limit. aMap(aKey) = anItem
	34	-- can be done only if aKey was previously bound to
	35	-- an item in the map.
	36	-- DataMap is a generic class which depends on three parameters:
	37	-- - Key is the type of key for an entry in the map,
	38	-- - Item is the type of element associated with a key in the map,
	39	-- - Hasher is the type of hasher on keys.
	40	-- Use a DataMapIterator iterator to explore a DataMap map.
	41	-- Notes:
	42	-- - An iterator class is automatically instantiated from the
	43	-- TCollection_DataMapIterator generic class at the
	44	-- time of instantiation of a DataMap map.
	45	-- - TCollection_MapHasher class describes the
	46	-- functions required for a Hasher object.
	47	raises
	48	DomainError from Standard,
	49	NoSuchObject from Standard
	50
	51	class DataMapNode from TCollection
	52	inherits MapNode from TCollection
	53
	54
	55
	56	uses MapNodePtr from TCollection
	57	is
	58	Create(K : TheKey; I : TheItem; n : MapNodePtr from TCollection) returns DataMapNode from TCollection;
	59	--- Purpose: Constructs a DataMap with NbBuckets (defaulted to 1) buckets.
	60	-- Note that the map will be automatically redimensioned
	61	-- during its use if the number of entries becomes too large.
	62	-- Use:
	63	-- - the function Bind to add an entry (key, item) in the map,
	64	-- - operator() to read an item from a key, or to assign a
	65	-- new value to this item,
	66	-- - the function UnBind to remove an entry (key, item) from the map,
	67	-- - and a map iterator to explore the map.
	68	---C++: inline
	69
	70	Key(me) returns TheKey;
	71	---C++: return &
	72	---C++: inline
	73
	74	Value(me) returns TheItem;
	75	---C++: return &
	76	---C++: inline
	77
	78	fields
	79	myKey : TheKey;
80	myValue : TheItem;
81	end;
82
83	class DataMapIterator inherits BasicMapIterator from TCollection
84	---Purpose: Functions used for iterating the contents of a DataMap
85	-- Note: an iterator class is automatically instantiated from
86	-- this generic class at the time of instantiation of a DataMap.
87	-- Warning
88	-- - A map is a non-ordered data structure. The order in
89	-- which entries of a map are explored by the iterator
90	-- depends on its contents, and change when the map is edited.
91	-- - It is not recommended to modify the contents of a map
92	-- during iteration: the result is unpredictable.
93
94	raises NoSuchObject from Standard
95	is
96	Create returns DataMapIterator from TCollection;
97	---Purpose: Creates an undefined Iterator (empty); use the function Initialize to define the map to explore.
98
99	Create (aMap : DataMap from TCollection)
100	returns DataMapIterator from TCollection;
101	---Purpose: Creates an Iterator on the map <aMap>.
102
103	Initialize(me : in out; aMap : DataMap from TCollection)
104	---Level: Public
105	---Purpose: Sets, or resets the Iterator in the map <aMap>.
106	is static;
107
108	Key(me) returns any TheKey
109	---Purpose: Returns the current Key. An error is raised if
110	-- the iterator is empty (More returns False).
111	-- Note: Key is the type of key for an entry in the explored DataMap map.
112	-- Exceptions
113	-- Standard_NoSuchObject if this iterator is empty (i.e.
114	-- when the function More returns false).
115	---C++: return const &
116	raises
117	NoSuchObject from Standard
118	is static;
119
120	Value(me) returns any TheItem
121	---Purpose: Returns the item of the current entry in the map for this iterator.
122	-- Note: Item is the type of element bound to a key in the explored DataMap map.
123	-- Exceptions
124	-- Standard_NoSuchObject if this iterator is empty (i.e.
125	-- when the function More returns false)
126	---C++: return const &
127	raises
128	NoSuchObject from Standard
129	is static;
130
131	end DataMapIterator from TCollection;
132
133	is
134	Create(NbBuckets : Integer = 1) returns DataMap from TCollection;
135	---Purpose: Creates a DataMap with <NbBuckets> buckets. Without
136	-- arguments the map is automatically dimensioned.
137
138
139	Create(Other : DataMap from TCollection) returns DataMap from TCollection
140	---Purpose: As copying Map is an expensive operation it is
141	-- incorrect to do it implicitly. This constructor is private and
142	-- will raise an error if the Map is not empty.
143	-- To copy the content of a DataMap use the Assign method (operator =).
144	raises DomainError from Standard
145	is private;
146
147	Assign(me : in out; Other : DataMap from TCollection)
148	returns DataMap from TCollection
149	---Purpose: Copies the contents of the map Other into this map.
150	-- Note that this method is an alias of operator =.
151	---C++: alias operator =
152	---C++: return &
153	is static;
154
155	ReSize(me : in out; NbBuckets : Integer)
156	---Level: Public
157	---Purpose: Changes the number of buckets of <me> to be
158	-- <NbBuckets>. The keys already stored in the map are kept.
159	is static;
160
161	Clear(me : in out)
162	---Purpose: Removes all keys in the map.
163	---C++: alias ~
164	is static;
165
166	Bind(me : in out; K : TheKey; I : TheItem) returns Boolean
167	---Purpose: Adds the Key <K> to the Map <me> with the Item
168	-- <I>. Returns True if the Key was not already in
169	-- the Map. If the Key was already in the Map the
170	-- Item in the Map is replaced.
171	is static;
172
173	IsBound(me; K : TheKey) returns Boolean
174	---Purpose: Returns True if the key <K> is stored in the map <me>.
175	is static;
176
177	UnBind(me : in out; K : TheKey) returns Boolean
178	---Purpose: Removes the Key <K> from the map. Returns True if
179	-- the Key was in the Map.
180	-- Returns false if the key K was not in this map.
181	is static;
182
183	Find(me; K : TheKey) returns any TheItem
184	---Level: Public
185	---Purpose: Returns the Item stored with the Key <K> in the Map.
186	-- Trigger: An exception is raised when <K> is not in the map.
187	raises NoSuchObject from Standard
188	---C++: alias operator()
189	---C++: return const &
190	is static;
191
192	ChangeFind(me : in out; K : TheKey) returns any TheItem
193	---Level: Public
194	---Purpose: Returns the Item stored with the Key <K> in the
195	-- Map. This Item can be modified with the syntax
196	-- aMap(K) = newItem;
197	-- Trigger: An exception is raised when <K> is not in the map.
198	---C++: alias operator()
199	---C++: return &
200	raises NoSuchObject from Standard
201	is static;
cf8e963a	202
	203	--modified by NIZNHY-PKV Tue Jul 05 09:57:10 2011f
	204	Find1(me; K : TheKey)
	205	returns Address from Standard;
	206	---Purpose: Returns the address of Item of the key <K>
	207	-- or NULL if K is not in the map.
	208	ChangeFind1(me:out; K : TheKey)
	209	returns Address from Standard;
	210	---Purpose: Returns the address of Item of the key <K>
	211	-- or NULL if K is not in the map.
	212	--modified by NIZNHY-PKV Tue Jul 05 09:57:14 2011t
	213
7fd59977	214	end DataMap;