File: /home/oboss/Users/gec/sources/Basic_Services/Containers/map_type.ads
1 --% Compilation Unit: Map_Type
2 --
3 --% Category: Generic Package Declaration
4 --
5 --% Release: $Name: $
6 --
7 --% Version: $Revision: 2.1 $
8 --
9 --% Author: $Author: gec $
10 --
11 --% Revision Log:
12 -- $Log: map_type.ads,v $
13 -- Revision 2.1 2003/04/30 10:53:13 gec
14 -- Corrected lacking error handling in case of exhaustion of an iterator.
15 -- The specified exception was not raised.
16 --
17 -- Revision 2.0 2003/04/04 08:49:56 gec
18 -- Initial release of source files serving as baseline for OBOSS-III
19 --+ project.
20 --
21 -- Revision 1.1.1.1 2003/04/04 08:13:00 gec
22 -- Imported using TkCVS
23 --
24 --
25 --
26 --% Project: OBOSS
27 --
28 --% Copyright (C) 2003 by Terma A/S
29 -- Proprietary and intellectual rights of Terma A/S, Denmark,
30 -- are involved in the subject-matter of this material and
31 -- all manufacturing, reproduction, use, disclosure, and
32 -- sales rights pertaining to such subject-matter are
33 -- expressly reserved. This material is submitted for a
34 -- specific purpose as agreed, and the recipient by
35 -- accepting this material agrees that this material will
36 -- not be used, copied, or reproduced in whole or in part
37 -- nor its contents revealed in any manner or to any person,
38 -- except to meet the purpose for which it was submitted and
39 -- subject to the terms of the agreement.
40 --
41 --% Target Dependencies:
42 -- None
43 --% Compiler Dependencies:
44 -- None
45
46 --~-----------------------------------------------------------------------------
47
48 generic
49
50 --% Generic Parameter Constraints:
51 --> None
52
53 -- Maximum number of entries to be contained in map.
54 Max_Number_Of_Entries : in Positive;
55
56 -- Type of keys used to look-up in map.
57 type Key_Type is (<>);
58
59 -- Type of elements associated to keys in map.
60 -- Access type included for efficiency reasons.
61 type Element_Type is private;
62 type Element_Type_Reference is access Element_Type;
63
64 package Map_Type is
65
66 --% Library Package:
67 -- Implementation of general map type associating data elements to keys.
68 -- Provides normal map operations as well as operations based on access
69 --+ type (avoids copying of large objects).
70 -- Access to map elements are based on locks being read-only or
71 --+ read-write.
72 -- Multiple read-only locks or one read-write lock can be obtained, but
73 --+ not both.
74 -- Deletion of locked elements is possible. The element will be deleted
75 --+ later when all locks have been released.
76 --% Active Tasks:
77 --> None
78 --% Passive Tasks:
79 --> None
80
81 -- A look-up operation failed as given key does not have an entry in map.
82 Not_In_Map : exception;
83
84 -- An insertion operation failed as given key already has an entry in map.
85 Already_In_Map : exception;
86
87 -- An insertion operation failed as number of map entries has reached
88 --+ Max_Number_Of_Entries.
89 Map_Size_Exceeded : exception;
90
91 -- Indicates that no elements are left in an iteration over the map domain
92 --+ or range
93 Iterator_Exhausted : exception;
94
95 -- Iterator over the map range, i.e. the data elements contained in the
96 --+ map.
97 type Map_Range is private;
98
99 -- Iterator over the map domain, i.e. the keys for which an entry exists in
100 --+ the map.
101 type Map_Domain is private;
102
103 procedure Initialize;
104
105 --------------------------------------
106 -- Normal map operations
107
108 --% Subprogram:
109 -- Remove any entries from the map, resulting in an empty map.
110 --% Parameter Constraints:
111 --> None
112 --% Exceptions Raised:
113 --> None
114 procedure Make_Map_Empty;
115
116 --% Subprogram:
117 -- Add an entry to the map, associating Elem to Key.
118 --% Parameter Constraints:
119 --> None
120 --% Exceptions Raised:
121 --> Already_In_Map - Map already contains an entry for Key
122 procedure Insert
123 (Key : in Key_Type;
124 Elem : in Element_Type);
125
126 --% Subprogram:
127 -- Remove the entry associating data to Key from the map.
128 --% Parameter Constraints:
129 --> None
130 --% Exceptions Raised:
131 --> Not_In_Map - Map does not contain an entry for Key
132 procedure Remove
133 (Key : in Key_Type);
134
135 --% Subprogram:
136 -- Replace the data element associated to Key with Elem.
137 --% Parameter Constraints:
138 --> None
139 --% Exceptions Raised:
140 --> Not_In_Map - Map does not contain an entry for Key
141 procedure Replace
142 (Key : in Key_Type;
143 Elem : in Element_Type);
144
145 --% Subprogram:
146 -- Look-up Key in map returning the data element associated to Key.
147 --% Parameter Constraints:
148 --> None
149 --% Exceptions Raised:
150 --> Not_In_Map - Map does not contain an entry for Key
151 function Apply
152 (Key : in Key_Type)
153 return Element_Type;
154
155 --% Subprogram:
156 -- Look-up Key in map returning accessor the data element associated to
157 --+ Key.
158 --% Parameter Constraints:
159 --> None
160 --% Exceptions Raised:
161 --> Not_In_Map - Map does not contain an entry for Key
162 function Apply
163 (Key : in Key_Type)
164 return Element_Type_Reference;
165
166 --% Subprogram:
167 -- Predicate indicating whether map contains an entry for Key.
168 --% Parameter Constraints:
169 --> None
170 --% Exceptions Raised:
171 --> None
172 function Is_In
173 (Key : in Key_Type)
174 return Boolean;
175
176 --------------------------------------------------------------
177 -- Operations on domain iterators
178
179 --% Subprogram:
180 -- Constructor for iterators over the map domain (i.e. the set of keys).
181 --% Parameter Constraints:
182 --> None
183 --% Exceptions Raised:
184 --> None
185 function Get_Domain
186 return Map_Domain;
187
188 --% Subprogram:
189 -- Predicate indicating whether the entire map domain has been covered by
190 --+ Iterator.
191 --% Parameter Constraints:
192 --> None
193 --% Exceptions Raised:
194 --> None
195 function Domain_Is_Covered
196 (Iterator : in Map_Domain)
197 return Boolean;
198
199 --% Subprogram:
200 -- Successor operator for domain iterators. Key is next key in iteration.
201 --+
202 --% Parameter Constraints:
203 --> None
204 --% Exceptions Raised:
205 --> Iterator_Exhausted - Entire domain has been covered by Iterator.
206 procedure Get_Next_Key_In_Domain
207 (Iterator : in out Map_Domain;
208 Key : out Key_Type);
209
210 --------------------------------------------------------------
211 -- Operations on range iterators
212
213 --% Subprogram:
214 -- Constructor for iterators over the map range (i.e. the set of data
215 --+ elements).
216 --% Parameter Constraints:
217 --> None
218 --% Exceptions Raised:
219 --> None
220 function Get_Range
221 return Map_Range;
222
223 --% Subprogram:
224 -- Predicate indicating whether the entire map range has been covered by
225 --+ Iterator.
226 --% Parameter Constraints:
227 --> None
228 --% Exceptions Raised:
229 --> None
230 function Range_Is_Covered
231 (Iterator : in Map_Range)
232 return Boolean;
233
234 --% Subprogram:
235 -- Successor operator for range iterators. Element is next data element
236 --+ in iteration.
237 --% Parameter Constraints:
238 --> None
239 --% Exceptions Raised:
240 --> Iterator_Exhausted - Entire range has been covered by Iterator.
241 procedure Get_Next_Element_In_Range
242 (Iterator : in out Map_Range;
243 Element : out Element_Type);
244
245 --% Subprogram:
246 -- Successor operator for range iterators. Element is next data element
247 --+ in iteration.
248 -- A lock of the class indicated by Lock is placed on element.
249 --% Parameter Constraints:
250 --> None
251 --% Exceptions Raised:
252 --> Iterator_Exhausted - Entire range has been covered by Iterator.
253 procedure Get_Next_Element_In_Range
254 (Iterator : in out Map_Range;
255 Element_Reference : out Element_Type_Reference);
256
257 private
258
259 type Map_Iterator is new Natural;
260 type Map_Range is new Map_Iterator;
261 type Map_Domain is new Map_Iterator;
262
263 end Map_Type;
264
265 --~-----------------------------------------------------------------------------
266