b311480e |
1 | -- Created on: 1993-01-07 |
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 Map from TCollection (TheKey as any; |
18 | Hasher as any) -- as MapHasher(TheKey) |
19 | inherits BasicMap from TCollection |
20 | |
21 | ---Purpose: Basic hashed Map. This Map is used to store and |
22 | -- retrieve keys in linear time. |
23 | -- |
24 | -- The MapIterator class can be used to explore the |
25 | -- content of the map. It is not wise to iterate and |
26 | -- modify a map in parallel. |
27 | -- |
28 | -- The Hasher argument is used to computes the |
29 | -- hashcode of key and compare two keys. |
30 | -- |
31 | -- The performance of a Map is conditionned by its |
32 | -- number of buckets that should be kept greater to |
33 | -- the number of keys. This map has an automatic |
34 | -- management of the number of buckets. It is resized |
35 | -- when the number of Keys becomes greater than the |
36 | -- number of buckets. |
37 | -- |
38 | -- If you have a fair idea of the number of objects |
39 | -- you can save on automatic resizing by giving a |
40 | -- number of buckets at creation or using the ReSize |
41 | -- method. This should be consider only for crucial |
42 | -- optimisation issues. |
43 | -- An entry of a Map is composed of the key only. No data is |
44 | -- attached to the key. A Map is typically used by an |
45 | -- algorithm to know if some action is still performed on |
46 | -- components of a complex data structure. |
47 | -- Map is a generic class which depends on two parameters: |
48 | -- - Key is the type of key in the map, |
49 | -- - Hasher is the type of hasher on keys. |
50 | -- Use a MapIterator iterator to explore a Map map. |
51 | -- Notes: |
52 | -- - An iterator class is automatically instantiated from the |
53 | -- TCollection_MapIterator class at the time of |
54 | -- instantiation of a Map map. |
55 | -- - TCollection_MapHasher class describes the |
56 | -- functions required for a Hasher object. |
57 | |
7fd59977 |
58 | |
59 | class StdMapNode from TCollection |
60 | inherits MapNode from TCollection |
61 | uses MapNodePtr from TCollection |
62 | is |
63 | Create(K : TheKey; n : MapNodePtr from TCollection) returns StdMapNode from TCollection; |
64 | ---C++: inline |
65 | |
66 | Key(me) returns TheKey; |
67 | ---C++: return & |
68 | ---C++: inline |
69 | |
70 | fields |
71 | myKey : TheKey; |
72 | end; |
73 | |
74 | class MapIterator inherits BasicMapIterator from TCollection |
75 | |
76 | ---Purpose: Provides iteration on the content of a map. The |
77 | -- iteration methods are inherited from the |
78 | -- BasicMapIterator. |
79 | -- Note: an iterator class is automatically instantiated from |
80 | -- this generic class at the time of instantiation of a <Map>. |
81 | -- Warning |
82 | -- - A map is a non-ordered data structure. The order in |
83 | -- which entries of a map are explored by the iterator |
84 | -- depends on its contents, and changes when the map is edited. |
85 | -- - It is not recommended to modify the contents of a map |
86 | -- during iteration: the result is unpredictable. |
87 | |
88 | raises NoSuchObject from Standard |
89 | is |
90 | Create returns MapIterator from TCollection; |
91 | ---Purpose: Creates an empty iterator for a Map map; use the function |
92 | -- Initialize to define the map to explore; |
93 | |
94 | Create (aMap : Map from TCollection) |
95 | returns MapIterator from TCollection; |
96 | ---Purpose: Creates an Iterator on the map <aMap>. |
97 | |
98 | Initialize(me : in out; aMap : Map from TCollection) |
99 | ---Purpose: Sets or resets the Iterator in the map <aMap>. |
100 | is static; |
101 | |
102 | Key(me) returns any TheKey |
103 | ---Purpose: Returns the current Key. An error is raised if |
104 | -- the iterator is empty (More returns False). |
105 | -- Note: Key is the type of key for an entry in the explored <Map>. |
106 | -- Exceptions |
107 | -- Standard_NoSuchObject if this iterator is empty (i.e. |
108 | -- when the function More returns false). |
109 | ---C++: return const & |
110 | raises |
111 | NoSuchObject from Standard |
112 | is static; |
113 | |
114 | end MapIterator from TCollection; |
115 | |
116 | is |
117 | |
118 | Create(NbBuckets : Integer = 1) returns Map from TCollection; |
119 | ---Purpose: Constructs a Map with NbBuckets (defaulted to 1) buckets. |
120 | -- Note that the map will be automatically redimensioned |
121 | -- during its use if the number of entries becomes too large. |
122 | -- Use: |
123 | -- - the function Add to add a new key in the map, |
124 | -- - the function Remove to remove a key from the map, |
125 | -- - and a map iterator to explore the map. |
126 | |
127 | |
214df550 |
128 | Create(Other : Map from TCollection) returns Map from TCollection; |
7fd59977 |
129 | ---Purpose: As copying Map is an expensive operation it is |
214df550 |
130 | -- not recommended to do it implicitly. |
7fd59977 |
131 | |
132 | Assign(me : in out; Other : Map from TCollection) |
133 | returns Map from TCollection |
134 | ---Purpose: Replace the content of this map by the content of |
135 | -- the map <Other>. |
136 | ---C++: alias operator = |
137 | ---C++: return & |
138 | is static; |
139 | |
140 | ReSize(me : in out; NbBuckets : Integer) |
141 | ---Purpose: Changes the number of buckets of <me> to be |
142 | -- <NbBuckets>. The keys already stored in the map are kept. |
143 | is static; |
144 | |
145 | Clear(me : in out) |
146 | ---Purpose: Removes all keys in the map. |
147 | ---C++: alias ~ |
148 | is static; |
149 | |
150 | Add(me : in out; aKey : TheKey) returns Boolean |
151 | ---Purpose: Adds the Key <aKey> to the Map <me>. Returns True |
152 | -- if the Key was not already in the Map. |
153 | is static; |
154 | |
155 | Contains(me; aKey : TheKey) returns Boolean |
156 | ---Purpose: Returns True if the key <aKey> is stored in the |
157 | -- map <me>. |
158 | is static; |
159 | |
160 | Remove(me : in out; aKey : TheKey) returns Boolean |
161 | ---Purpose: Removes the Key <aKey> from the map. Returns True |
162 | -- if the Key was in the Map. |
163 | is static; |
164 | |
165 | end Map; |