7fd59977 |
1 | -- File: TCollection_Stack.cdl |
2 | -- Created: Mon Jan 18 10:45:24 1993 |
3 | -- Author: Remi LEQUETTE |
4 | -- <rle@phylox> |
5 | -- Updated: M. MERCIEN 26, Oct 1994 |
6 | -- Subject: StackIterator implementation |
7 | ---Copyright: Matra Datavision 1993 |
8 | |
9 | |
10 | generic class Stack from TCollection (Item as any) |
11 | |
12 | ---Purpose: A stack is a structure where item can be added and |
13 | -- removed from the top. Like a stack of plates in a |
14 | -- kitchen. The last entered item will be be the |
15 | -- first removed. This is called a LIFO (last In First Out). |
16 | -- Stack is a generic class which depends on Item, the type |
17 | -- of element in the structure. |
18 | -- Use a StackIterator iterator to explore a Stack structure. |
19 | -- Note: An iterator class is automatically instantiated from |
20 | -- the TCollection_StackIterator class at the time of |
21 | -- instantiation of a Stack structure. |
22 | raises |
23 | NoSuchObject from Standard |
24 | |
25 | class StackNode from TCollection |
26 | inherits MapNode from TCollection |
27 | uses MapNodePtr from TCollection |
28 | is |
29 | Create(I : Item; n : MapNodePtr from TCollection) returns StackNode from TCollection; |
30 | ---C++: inline |
31 | |
32 | Value(me) returns Item; |
33 | ---C++: return & |
34 | ---C++: inline |
35 | |
36 | fields |
37 | myValue : Item; |
38 | end; |
39 | |
40 | class StackIterator from TCollection |
41 | ---Purpose: Functions used for iterating the contents of a Stack data structure. |
42 | -- Note: an iterator class is automatically instantiated from |
43 | -- this generic class at the time of instantiation of a Stack structure. |
44 | |
45 | raises NoSuchObject from Standard |
46 | is |
47 | Create returns StackIterator from TCollection; |
48 | ---Purpose: Constructs an empty iterator for a Stack data structure. |
49 | -- Use the function Initialize to define the stack to explore. |
50 | |
51 | Create(S : Stack from TCollection) returns StackIterator from TCollection; |
52 | ---Purpose: Constructs an iterator on the stack stack, and positions it |
53 | -- on the first item of the stack stack, if it exists. |
54 | -- The current position is undefined if the stack stack is empty. |
55 | -- Use in a loop: |
56 | -- - the function More to know if there is a current item, |
57 | -- - then the function Value to read the value of the current item, |
58 | -- - then the function Next to position the iterator on the |
59 | -- next item, if it exists. |
60 | |
61 | Initialize(me : in out; S : Stack from TCollection) |
62 | ---Purpose: Sets, or resets this iterator for the stack stack, and |
63 | -- positions it on the first item of the stack stack, if it exists. |
64 | -- The current position is undefined if the stack stack is empty. |
65 | -- Example |
66 | -- TColStd_StackOfInteger stack; |
67 | -- TColStd_StackIteratorOfStackOfInteger |
68 | -- pos; |
69 | -- pos.Initialize(stack); |
70 | -- Use in a loop: |
71 | -- - the function More to know if there is a current item, |
72 | -- - then the function Value to read the value of the current item, |
73 | -- - then the function Next to position the iterator on the |
74 | -- next item, if it exists. |
75 | is static; |
76 | |
77 | More(me) returns Boolean from Standard |
78 | ---Purpose:Returns true if there is a current item in the stack explored |
79 | -- with this iterator (i.e. when the current position is defined). |
80 | -- More is false if: |
81 | -- - the iterator is not initialized, or |
82 | -- - the stack is empty, or |
83 | -- - the exploration is finished. |
84 | -- Use: |
85 | -- - the function Value to read the current item, |
86 | -- - the function Next to position this iterator on the next item, if it exists. |
87 | ---C++: inline |
88 | is static; |
89 | |
90 | Next(me: in out) |
91 | ---Purpose: Sets the iterator to the next item in the explored stack. |
92 | -- If the current position of this iterator corresponds to the |
93 | -- top of the stack, it becomes undefined. |
94 | is static; |
95 | |
96 | Value(me) returns any Item |
97 | raises NoSuchObject from Standard |
98 | ---Purpose: Returns the value of the current item of this iterator in the explored stack. |
99 | -- Note: Item is the type of element in the explored Stack stack. |
100 | -- Example |
101 | -- TColStd_StackOfInteger stack; |
102 | -- TColStd_StackIteratorOfStackOfInteger |
103 | -- pos(stack); |
104 | -- stack.Push(1); |
105 | -- assert ( pos.Value() == 1 ); |
106 | -- Exceptions |
107 | -- Standard_NoSuchObject if the current position of this |
108 | -- iterator is undefined. |
109 | ---C++: return const & |
110 | is static; |
111 | |
112 | fields |
113 | current : Address from Standard; |
114 | |
115 | end StackIterator from TCollection; |
116 | |
117 | is |
118 | Create returns Stack from TCollection; |
119 | ---Purpose: Constructs an empty stack. |
120 | -- Use: |
121 | -- - the function Push to add an item at the top of the stack, |
122 | -- - the function Top to read the item at the top of the stack, |
123 | -- - the function ChangeTop to assign a new value to the |
124 | -- item at the top of the stack, |
125 | -- - the function Pop to remove the item at the top of the stack, |
126 | -- - and a stack iterator to explore the stack and read all its items. |
127 | -- Warning |
128 | -- To copy a stack, you must explicitly call the assignment |
129 | -- operator (operator=).. |
130 | |
131 | Create(Other : Stack from TCollection) |
132 | returns Stack from TCollection |
133 | is private; |
134 | ---Purpose: Creates by copying an existing Stack. |
135 | -- Warning: Prints a message when other is not empty. It is |
136 | -- recommanded to use Assign (operator =). |
137 | |
138 | Assign(me : in out; Other : Stack from TCollection) |
139 | returns Stack from TCollection |
140 | ---Purpose: Copies in this stack the content of <Other>. |
141 | --If this stack is not empty, it is automatically cleared before copying. |
142 | -- Note that this method is an alias of the assignment |
143 | -- operator operator =. |
144 | ---C++: alias operator = |
145 | ---C++: return const & |
146 | is static; |
147 | |
148 | IsEmpty(me) returns Boolean |
149 | ---Purpose: Returns True when the stack is empty. |
150 | -- i.e. Depth() == 0 |
151 | ---C++: inline |
152 | is static; |
153 | |
154 | Depth(me) returns Integer |
155 | ---Level: Public |
156 | ---Purpose: Returns the number of Items in the stack. |
157 | -- The depth of this stack is: |
158 | -- - incremented by Push, and |
159 | -- - decremented by Pop. |
160 | -- Example: |
161 | -- me = (A B C) |
162 | -- returns 3 |
163 | ---C++: inline |
164 | is static; |
165 | |
166 | Top(me) returns any Item |
167 | ---Level: Public |
168 | ---Purpose: Returns the Item at the top of the stack. |
169 | -- Example: |
170 | -- before |
171 | -- me = (A B C) |
172 | -- after |
173 | -- me = (A B C) |
174 | -- returns |
175 | -- A |
176 | -- Trigger: Raises an exception when <me> is empty |
177 | ---C++: return const & |
178 | raises NoSuchObject from Standard |
179 | is static; |
180 | |
181 | Push(me : in out; I : Item) |
182 | ---Level: Public |
183 | ---Purpose: Adds <I> at the top of the stack. Depth is |
184 | -- incremented. |
185 | -- Example: |
186 | -- before |
187 | -- me = (A B C) I = D |
188 | -- after |
189 | -- me = (D A B C) |
190 | is static; |
191 | |
192 | Pop(me : in out) |
193 | ---Level: Public |
194 | ---Purpose: Removes the Item at the top of the stack. Depth is |
195 | -- decremented. |
196 | -- Example: |
197 | -- before |
198 | -- me = (A B C) |
199 | -- after |
200 | -- me = (B C) |
201 | -- Trigger: Raises an exception when <me> is empty |
202 | raises NoSuchObject from Standard |
203 | is static; |
204 | |
205 | Clear(me : in out) |
206 | ---Level: Public |
207 | ---Purpose: Removes all the items from the stack. |
208 | ---C++: alias ~ |
209 | is static; |
210 | |
211 | ChangeTop(me : in out) returns any Item |
212 | ---Level: Public |
213 | ---Purpose: Returns a modifiable reference of the top of the stack. |
214 | -- Example: |
215 | -- before |
216 | -- me = (A B C) |
217 | -- me.ChangeTop() = D |
218 | -- after |
219 | -- me = (D B C) |
220 | -- Trigger: Raises an exception when <me> is empty |
221 | raises NoSuchObject from Standard |
222 | ---C++: return & |
223 | is static; |
224 | |
225 | fields |
226 | |
227 | myTop : Address from Standard; |
228 | myDepth : Integer from Standard; |
229 | |
230 | friends |
231 | class StackIterator from TCollection |
232 | |
233 | end Stack; |