1 -- Created on: 1992-12-17
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1992-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
6 -- This file is part of Open CASCADE Technology software library.
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
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.
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
17 generic class List from TCollection (Item as any)
18 ---Purpose: Ordered lists of non-unique objects which can be
19 -- accessed sequentially using an iterator.
20 -- Item insertion in a list is very fast at any position. But
21 -- searching for items by value may be slow if the list is long,
22 -- because it requires a sequential search.
23 -- List is a generic class which depends on Item, the type of
24 -- element in the structure.
25 -- Use a ListIterator iterator to explore a List structure.
27 -- - An iterator class is automatically instantiated from the
28 -- TCollection_ListIterator class at the time of
29 -- instantiation of a List structure.
30 -- - A sequence is a better structure when searching for
31 -- items by value is an important goal for a data structure.
32 -- - Queues and stacks are other kinds of list with a
33 -- different access to data.
36 Address from Standard,
40 NoSuchObject from Standard
42 class ListNode from TCollection
43 inherits MapNode from TCollection
44 uses MapNodePtr from TCollection
46 Create(I : Item; n : MapNodePtr from TCollection) returns ListNode from TCollection;
49 Value(me) returns Item;
58 ---Purpose: Functions used for iterating the contents of a List data structure.
59 -- A ListIterator object can be used to go through a list
60 -- sequentially, and to hold a position in a list as a
61 -- bookmark. It is not an index, however. Each step of the
62 -- iteration gives the current position of the iterator, to
63 -- which corresponds the current item in the list. The
64 -- current position is undefined if the list is empty, or when
65 -- the exploration is finished.
66 -- Note: an iterator class is automatically instantiated from
67 -- this generic class at the time of instantiation of a List
70 NoMoreObject from Standard,
71 NoSuchObject from Standard
75 Create returns ListIterator;
76 ---Purpose: Constructs an empty iterator for a List data structure. Use
77 -- the function Initialize to define the list to explore.
79 Create(L : List) returns ListIterator;
80 ---Purpose: Constructs an iterator on the list list, and positions it on
81 -- the first item of the list list, if it exists.
82 -- The current position is undefined if the list list is empty.
84 -- - the function More to know if there is a current item,
85 -- - then the function Value to read the value of the current item,
86 -- - then the function Next to position the iterator on the
87 -- next item, if it exists.
89 Initialize(me : in out; L : List)
90 ---Purpose: Sets, or resets this iterator for the list list, and positions it
91 -- on the first item of the list list, if it exists.
92 -- The current position is undefined if the list list is empty.
94 -- TColStd_ListOfInteger list;
95 -- TColStd_ListIteratorOfListOfInteger
97 -- pos.Initialize(list);
99 -- - the function More to know if there is a current item,
100 -- - then the function Value to read the value of the current item,
101 -- - then the function Next to position the iterator on the
102 -- next item, if it exists.
105 More(me) returns Boolean from Standard
106 ---Purpose: Returns true if there is a current item in the list explored
107 -- with this iterator (i.e. when the current position is defined).
109 -- - the iterator is not initialized, or
110 -- - the list is empty, or
111 -- - the exploration is finished.
113 -- - the function Value to read the current item,
114 -- - the function Next to position this iterator on the next item, if it exists.
116 -- Standard_Integer i;
117 -- TColStd_ListOfInteger s;
118 -- TColStd_ListIteratorOfListOfInteger
129 ---Purpose: Sets this iterator on the next item in the explored list.
130 -- If the current position of this iterator corresponds to the
131 -- last item in the list, it becomes undefined.
133 -- Standard_NoMoreObject if the current position of this
134 -- iterator is undefined.
136 NoMoreObject from Standard
139 Value(me) returns any Item
140 ---Purpose: Returns the value of the current item of this iterator in the
142 -- Note: Item is the type of element in the explored List list.
144 -- TColStd_ListOfInteger s;
145 -- TColStd_ListIteratorOfListOfInteger
148 -- assert (pos.Value() == s.First() );
150 -- Standard_NoSuchObject if the current position of this
151 -- iterator is undefined.
154 NoSuchObject from Standard
158 current : Address from Standard;
159 previous : Address from Standard;
162 class List from TCollection
164 end ListIterator from TCollection;
167 Create returns List from TCollection;
168 ---Purpose: Constructs an empty list.
170 -- - the function Append or Prepend to add an item or a
171 -- collection of items at the end, or at the beginning of the list,
172 -- - a list iterator to explore the list and read its items,
173 -- - and in conjunction with this iterator:
174 -- - the function InsertAfter or InsertBefore to add an
175 -- item or a collection of items at any position in the list,
176 -- - the function Remove to remove an item at any position in the list.
178 -- To copy a list, you must explicitly call the assignment operator (operator=).
180 Create(Other : List from TCollection)
181 returns List from TCollection;
182 ---Purpose: Creation by copy of existing list.
183 -- We recommend to use the operator =.
185 Assign(me : in out; Other : List from TCollection)
186 ---Purpose: Replace <me> by a copy of <Other>.
187 ---C++: alias operator=
190 Extent(me) returns Integer
191 ---Purpose: Returns the number of items.
195 ---Purpose: Clears the content of the list <me>.
199 IsEmpty(me) returns Boolean from Standard
200 ---Purpose: Returns true if this list is empty.
204 Prepend(me : in out; I : Item)
206 ---Purpose: Insert the Item <I> at the head of the list.
209 -- san: 18/04/2003 - addition methods returns ListIterator
210 Prepend(me : in out; I : Item; theIt : in out ListIterator )
212 ---Purpose: Insert the Item <I> at the head of the list.
213 --- Returns ListIterator pointing to the first Item.
216 Prepend(me : in out; Other : in out List from TCollection)
218 ---Purpose: Insert the list <Other> at the head of <me>.
219 --- <Other> is cleared.
222 Append(me : in out; I : Item)
224 ---Purpose: Insert the Item <I> at the end of the list.
227 -- san: 18/04/2003 - addition methods returns ListIterator
228 Append(me : in out; I : Item; theIt : in out ListIterator )
230 ---Purpose: Insert the Item <I> at the head of the list.
231 --- Returns ListIterator pointing to the first Item.
234 Append(me : in out; Other : in out List from TCollection)
236 ---Purpose: Append the list <L> at the end of <me>.
237 --- <Other> is cleared.
240 First(me) returns any Item
241 ---Purpose: Returns the first Item in the list, may be modified.
242 -- Trigger: Raises an exception when the list is empty.
245 NoSuchObject from Standard
248 Last(me) returns any Item
249 ---Purpose: Returns the last Item in the list, may be modified.
250 -- Trigger: Raises an exception when the list is empty.
253 NoSuchObject from Standard
256 RemoveFirst(me : in out)
257 ---Purpose: Removes the first Item from the list. Nothing is
258 -- done if the list is empty.
261 Remove(me : in out; It : in out ListIterator)
262 ---Purpose: Removes the current Item of the ListIterator from the
263 -- List. The ListIterator current will be the next Item
266 -- Standard_NoSuchObject if the current position of the
267 -- list iterator pos is undefined.
269 NoSuchObject from Standard
272 InsertBefore (me : in out; I : Item;
273 It : in out ListIterator)
275 ---Purpose: Insert <I> in the List before the current position
276 -- of <It>. It is not change.
278 NoSuchObject from Standard
281 InsertBefore (me : in out; Other : in out List from TCollection;
282 It : in out ListIterator)
284 ---Purpose: Insert <Other> in the List before the current position
285 -- of <It>. <It> is not change. <Other> is cleared.
287 NoSuchObject from Standard
290 InsertAfter (me : in out; I : Item;
291 It : in out ListIterator)
293 ---Purpose: Insert <I> in the List after the current position
294 -- if <It>. <It> is not changed.
297 InsertAfter (me : in out; Other : in out List from TCollection;
298 It : in out ListIterator)
300 ---Purpose: Insert <Other> in the List after the current position
301 -- if <It>. <It> is not changed. <Other> is cleared.
305 myFirst : Address from Standard;
306 myLast : Address from Standard;
309 class ListIterator from TCollection