src/TCollection/TCollection_List.cdl

   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
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   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.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  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.
  26     -- Notes:
  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.
  34
  35     uses
  36         Address from Standard,
  37         Boolean from Standard
  38
  39     raises
  40         NoSuchObject from Standard
  41
  42         class ListNode from TCollection
  43             inherits MapNode from TCollection
  44             uses MapNodePtr from TCollection
  45             is
  46               Create(I : Item; n : MapNodePtr from TCollection) returns ListNode from TCollection;
  47               ---C++: inline
  48
  49               Value(me) returns Item;
  50               ---C++: return &
  51               ---C++: inline
  52
  53          fields
  54               myValue : Item;
  55          end;
  56
  57         class ListIterator
  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
  68                 -- data structure.
  69         raises
  70             NoMoreObject from Standard,
  71             NoSuchObject from Standard
  72
  73         is
  74
  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.
  78
  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.
  83                 -- Use in a loop:
  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.
  88
  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.
  93                 -- Example
  94                 -- TColStd_ListOfInteger list;
  95                 -- TColStd_ListIteratorOfListOfInteger
  96                 -- pos;
  97                 -- pos.Initialize(list);
  98                 -- Use in a loop:
  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.
 103             is static;
 104
 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).
 108                 -- More is false if:
 109                 -- -   the iterator is not initialized, or
 110                 -- -   the list is empty, or
 111                 -- -   the exploration is finished.
 112                 --  Use:
 113                 -- -   the function Value to read the current item,
 114                 -- -   the function Next to position this iterator on the next   item, if it exists.
 115                 --   Example
 116                 -- Standard_Integer i;
 117                 -- TColStd_ListOfInteger s;
 118                 -- TColStd_ListIteratorOfListOfInteger
 119                 -- pos(s);
 120                 -- while(pos.More())
 121                 -- {
 122                 -- i = pos.Value();
 123                 -- pos.Next();
 124                 -- }
 125                 ---C++: inline
 126             is static;
 127
 128             Next(me : in out)
 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.
 132                 -- Exceptions
 133                 -- Standard_NoMoreObject if the current position of this
 134                 -- iterator is undefined.
 135             raises
 136                 NoMoreObject from Standard
 137             is static;
 138
 139             Value(me) returns any Item
 140                 ---Purpose: Returns the value of the current item of this iterator in the
 141                 -- explored list.
 142                 -- Note: Item is the type of element in the explored List list.
 143                 -- Example
 144                 -- TColStd_ListOfInteger          s;
 145                 -- TColStd_ListIteratorOfListOfInteger
 146                 -- pos(s);
 147                 -- s.Append(1);
 148                 -- assert (pos.Value() == s.First() );
 149                 -- Exceptions
 150                 -- Standard_NoSuchObject if the current position of this
 151                 -- iterator is undefined.
 152                 ---C++: return &
 153             raises
 154                 NoSuchObject from Standard
 155             is static;
 156
 157         fields
 158             current  : Address from Standard;
 159             previous : Address from Standard;
 160
 161         friends
 162             class List from TCollection
 163
 164         end ListIterator from TCollection;
 165 is
 166
 167     Create returns List from TCollection;
 168         ---Purpose: Constructs an empty list.
 169         -- Use:
 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.
 177         --    Warning
 178         -- To copy a list, you must explicitly call the assignment operator (operator=).
 179
 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 =.
 184
 185     Assign(me : in out; Other : List from TCollection)
 186         ---Purpose: Replace <me> by a copy of <Other>.
 187         ---C++: alias operator=
 188     is static;
 189
 190     Extent(me) returns Integer
 191         ---Purpose: Returns the number of items.
 192     is static;
 193
 194     Clear(me : in out)
 195         ---Purpose: Clears the content of the list <me>.
 196         ---C++: alias ~
 197     is static;
 198
 199     IsEmpty(me) returns Boolean from Standard
 200         ---Purpose: Returns true if this list is empty.
 201         ---C++: inline
 202     is static;
 203
 204     Prepend(me : in out; I : Item)
 205         ---Level: Public
 206         ---Purpose: Insert the Item <I> at the head of the list.
 207     is static;
 208
 209     -- san: 18/04/2003 - addition methods returns ListIterator
 210     Prepend(me : in out; I : Item; theIt : in out ListIterator )
 211         ---Level: Public
 212         ---Purpose: Insert the Item <I> at the head of the list.
 213         ---         Returns ListIterator pointing to the first Item.
 214     is static;
 215
 216     Prepend(me : in out; Other : in out List from TCollection)
 217         ---Level: Public
 218         ---Purpose: Insert  the  list <Other>  at  the  head  of <me>.
 219         ---         <Other> is cleared.
 220     is static;
 221
 222     Append(me : in out; I : Item)
 223         ---Level: Public
 224         ---Purpose: Insert the Item <I> at the end of the list.
 225     is static;
 226
 227     -- san: 18/04/2003 - addition methods returns ListIterator
 228     Append(me : in out; I : Item; theIt : in out ListIterator )
 229         ---Level: Public
 230         ---Purpose: Insert the Item <I> at the head of the list.
 231         ---         Returns ListIterator pointing to the first Item.
 232     is static;
 233
 234     Append(me : in out; Other : in out List from TCollection)
 235         ---Level: Public
 236         ---Purpose: Append the list <L> at the end of <me>.
 237         ---         <Other> is cleared.
 238     is static;
 239
 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.
 243         ---C++: return &
 244     raises
 245         NoSuchObject from Standard
 246     is static;
 247
 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.
 251         ---C++: return &
 252     raises
 253         NoSuchObject from Standard
 254     is static;
 255
 256     RemoveFirst(me : in out)
 257         ---Purpose: Removes the first  Item from the  list. Nothing is
 258         -- done if the list is empty.
 259     is static;
 260
 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
 264         -- in the list.
 265         -- Exceptions
 266         -- Standard_NoSuchObject if the current position of the
 267         -- list iterator pos is undefined.
 268     raises
 269         NoSuchObject from Standard
 270     is static;
 271
 272     InsertBefore (me : in out; I : Item;
 273                   It : in out ListIterator)
 274         ---Level: Public
 275         ---Purpose: Insert <I> in the List before the current position
 276         -- of <It>. It is not change.
 277     raises
 278         NoSuchObject from Standard
 279     is static;
 280
 281     InsertBefore (me : in out; Other : in out List from TCollection;
 282                   It : in out ListIterator)
 283         ---Level: Public
 284         ---Purpose: Insert <Other> in the List before the current position
 285         -- of <It>. <It> is not change. <Other> is cleared.
 286     raises
 287         NoSuchObject from Standard
 288     is static;
 289
 290     InsertAfter (me : in out; I : Item;
 291                  It : in out ListIterator)
 292         ---Level: Public
 293         ---Purpose: Insert <I> in the List after the  current position
 294         -- if <It>. <It> is not changed.
 295     is static;
 296
 297     InsertAfter (me : in out; Other : in out List from TCollection;
 298                  It : in out ListIterator)
 299         ---Level: Public
 300         ---Purpose: Insert <Other> in the List after the  current position
 301         -- if <It>. <It> is not changed. <Other> is cleared.
 302     is static;
 303
 304 fields
 305     myFirst : Address from Standard;
 306     myLast  : Address from Standard;
 307
 308 friends
 309     class ListIterator from TCollection
 310
 311 end List;
 312
 313
 314