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 |
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 |
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; |