src/TCollection/TCollection_List.cdl

   1 -- File:        TCollection_List.cdl
   2 -- Created:     Thu Dec 17 12:04:18 1992
   3 -- Author:      Remi LEQUETTE
   4 --              <rle@phobox>
   5 ---Copyright:    Matra Datavision 1992
   6
   7 generic class List from TCollection (Item as any)
   8     ---Purpose: Ordered lists of non-unique objects which can be
   9     -- accessed sequentially using an iterator.
  10     -- Item insertion in a list is very fast at any position. But
  11     -- searching for items by value may be slow if the list is long,
  12     -- because it requires a sequential search.
  13     -- List is a generic class which depends on Item, the type of
  14     -- element in the structure.
  15     -- Use a ListIterator iterator to explore a List structure.
  16     -- Notes:
  17     -- -   An iterator class is automatically instantiated from the
  18     --   TCollection_ListIterator class at the time of
  19     --   instantiation of a List structure.
  20     -- -   A sequence is a better structure when searching for
  21     --   items by value is an important goal for a data structure.
  22     -- -   Queues and stacks are other kinds of list with a
  23     --   different access to data.
  24
  25     uses
  26         Address from Standard,
  27         Boolean from Standard
  28
  29     raises
  30         NoSuchObject from Standard
  31
  32         class ListNode from TCollection
  33             inherits MapNode from TCollection
  34             uses MapNodePtr from TCollection
  35             is
  36               Create(I : Item; n : MapNodePtr from TCollection) returns ListNode from TCollection;
  37               ---C++: inline
  38
  39               Value(me) returns Item;
  40               ---C++: return &
  41               ---C++: inline
  42
  43          fields
  44               myValue : Item;
  45          end;
  46
  47         class ListIterator
  48                 ---Purpose: Functions used for iterating the contents of a List data structure.
  49                 -- A ListIterator object can be used to go through a list
  50                 -- sequentially, and to hold a position in a list as a
  51                 -- bookmark. It is not an index, however. Each step of the
  52                 -- iteration gives the current position of the iterator, to
  53                 -- which corresponds the current item in the list. The
  54                 -- current position is undefined if the list is empty, or when
  55                 -- the exploration is finished.
  56                 -- Note: an iterator class is automatically instantiated from
  57                 -- this generic class at the time of instantiation of a List
  58                 -- data structure.
  59         raises
  60             NoMoreObject from Standard,
  61             NoSuchObject from Standard
  62
  63         is
  64
  65             Create returns ListIterator;
  66                 ---Purpose: Constructs an empty iterator for a List data structure. Use
  67                 -- the function Initialize to define the list to explore.
  68
  69             Create(L : List) returns ListIterator;
  70                 ---Purpose: Constructs an iterator on the list list, and positions it on
  71                 -- the first item of the list list, if it exists.
  72                 -- The current position is undefined if the list list is empty.
  73                 -- Use in a loop:
  74                 -- -   the function More to know if there is a current item,
  75                 -- -   then the function Value to read the value of the current   item,
  76                 -- -   then the function Next to position the iterator on the
  77                 --   next item, if it exists.
  78
  79             Initialize(me : in out; L : List)
  80                 ---Purpose: Sets, or resets this iterator for the list list, and positions it
  81                 -- on the first item of the list list, if it exists.
  82                 -- The current position is undefined if the list list is empty.
  83                 -- Example
  84                 -- TColStd_ListOfInteger list;
  85                 -- TColStd_ListIteratorOfListOfInteger
  86                 -- pos;
  87                 -- pos.Initialize(list);
  88                 -- Use in a loop:
  89                 -- -   the function More to know if there is a current item,
  90                 -- -   then the function Value to read the value of the current   item,
  91                 -- -   then the function Next to position the iterator on the
  92                 --   next item, if it exists.
  93             is static;
  94
  95             More(me) returns Boolean from Standard
  96                 ---Purpose: Returns true if there is a current item in the list explored
  97                 -- with this iterator (i.e. when the current position is defined).
  98                 -- More is false if:
  99                 -- -   the iterator is not initialized, or
 100                 -- -   the list is empty, or
 101                 -- -   the exploration is finished.
 102                 --  Use:
 103                 -- -   the function Value to read the current item,
 104                 -- -   the function Next to position this iterator on the next   item, if it exists.
 105                 --   Example
 106                 -- Standard_Integer i;
 107                 -- TColStd_ListOfInteger s;
 108                 -- TColStd_ListIteratorOfListOfInteger
 109                 -- pos(s);
 110                 -- while(pos.More())
 111                 -- {
 112                 -- i = pos.Value();
 113                 -- pos.Next();
 114                 -- }
 115                 ---C++: inline
 116             is static;
 117
 118             Next(me : in out)
 119                 ---Purpose: Sets this iterator on the next item in the explored list.
 120                 -- If the current position of this iterator corresponds to the
 121                 -- last item in the list, it becomes undefined.
 122                 -- Exceptions
 123                 -- Standard_NoMoreObject if the current position of this
 124                 -- iterator is undefined.
 125             raises
 126                 NoMoreObject from Standard
 127             is static;
 128
 129             Value(me) returns any Item
 130                 ---Purpose: Returns the value of the current item of this iterator in the
 131                 -- explored list.
 132                 -- Note: Item is the type of element in the explored List list.
 133                 -- Example
 134                 -- TColStd_ListOfInteger          s;
 135                 -- TColStd_ListIteratorOfListOfInteger
 136                 -- pos(s);
 137                 -- s.Append(1);
 138                 -- assert (pos.Value() == s.First() );
 139                 -- Exceptions
 140                 -- Standard_NoSuchObject if the current position of this
 141                 -- iterator is undefined.
 142                 ---C++: return &
 143             raises
 144                 NoSuchObject from Standard
 145             is static;
 146
 147         fields
 148             current  : Address from Standard;
 149             previous : Address from Standard;
 150
 151         friends
 152             class List from TCollection
 153
 154         end ListIterator from TCollection;
 155 is
 156
 157     Create returns List from TCollection;
 158         ---Purpose: Constructs an empty list.
 159         -- Use:
 160         -- -   the function Append or Prepend to add an item or a
 161         -- collection of items at the end, or at the beginning of the   list,
 162         -- -   a list iterator to explore the list and read its items,
 163         -- -   and in conjunction with this iterator:
 164         --   -   the function InsertAfter or InsertBefore to add an
 165         --    item or a collection of items at any position in the list,
 166         -- -   the function Remove to remove an item at any position in the list.
 167         --    Warning
 168         -- To copy a list, you must explicitly call the assignment operator (operator=).
 169
 170     Create(Other : List from TCollection)
 171      returns List from TCollection
 172      is private;
 173         ---Purpose: Creation by copy of existing list.
 174         --  Warning: This constructor prints a warning message.
 175         -- We recommand to use the operator =.
 176
 177     Assign(me : in out; Other : List from TCollection)
 178         ---Purpose: Replace <me> by a copy of <Other>.
 179         ---C++: alias operator=
 180     is static;
 181
 182     Extent(me) returns Integer
 183         ---Purpose: Returns the number of items.
 184     is static;
 185
 186     Clear(me : in out)
 187         ---Purpose: Clears the content of the list <me>.
 188         ---C++: alias ~
 189     is static;
 190
 191     IsEmpty(me) returns Boolean from Standard
 192         ---Purpose: Returns true if this list is empty.
 193         ---C++: inline
 194     is static;
 195
 196     Prepend(me : in out; I : Item)
 197         ---Level: Public
 198         ---Purpose: Insert the Item <I> at the head of the list.
 199     is static;
 200
 201     -- san: 18/04/2003 - addition methods returns ListIterator
 202     Prepend(me : in out; I : Item; theIt : in out ListIterator )
 203         ---Level: Public
 204         ---Purpose: Insert the Item <I> at the head of the list.
 205         ---         Returns ListIterator pointing to the first Item.
 206     is static;
 207
 208     Prepend(me : in out; Other : in out List from TCollection)
 209         ---Level: Public
 210         ---Purpose: Insert  the  list <Other>  at  the  head  of <me>.
 211         ---         <Other> is cleared.
 212     is static;
 213
 214     Append(me : in out; I : Item)
 215         ---Level: Public
 216         ---Purpose: Insert the Item <I> at the end of the list.
 217     is static;
 218
 219     -- san: 18/04/2003 - addition methods returns ListIterator
 220     Append(me : in out; I : Item; theIt : in out ListIterator )
 221         ---Level: Public
 222         ---Purpose: Insert the Item <I> at the head of the list.
 223         ---         Returns ListIterator pointing to the first Item.
 224     is static;
 225
 226     Append(me : in out; Other : in out List from TCollection)
 227         ---Level: Public
 228         ---Purpose: Append the list <L> at the end of <me>.
 229         ---         <Other> is cleared.
 230     is static;
 231
 232     First(me) returns any Item
 233         ---Purpose: Returns   the  first  Item in   the  list, may  be modified.
 234         --  Trigger: Raises an exception when the list is empty.
 235         ---C++: return &
 236     raises
 237         NoSuchObject from Standard
 238     is static;
 239
 240     Last(me) returns any Item
 241         ---Purpose: Returns   the  last 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     RemoveFirst(me : in out)
 249         ---Purpose: Removes the first  Item from the  list. Nothing is
 250         -- done if the list is empty.
 251     is static;
 252
 253     Remove(me : in out; It : in out ListIterator)
 254         ---Purpose: Removes the current  Item of the ListIterator from the
 255         -- List.  The ListIterator current will  be the next Item
 256         -- in the list.
 257         -- Exceptions
 258         -- Standard_NoSuchObject if the current position of the
 259         -- list iterator pos is undefined.
 260     raises
 261         NoSuchObject from Standard
 262     is static;
 263
 264     InsertBefore (me : in out; I : Item;
 265                   It : in out ListIterator)
 266         ---Level: Public
 267         ---Purpose: Insert <I> in the List before the current position
 268         -- of <It>. It is not change.
 269     raises
 270         NoSuchObject from Standard
 271     is static;
 272
 273     InsertBefore (me : in out; Other : in out List from TCollection;
 274                   It : in out ListIterator)
 275         ---Level: Public
 276         ---Purpose: Insert <Other> in the List before the current position
 277         -- of <It>. <It> is not change. <Other> is cleared.
 278     raises
 279         NoSuchObject from Standard
 280     is static;
 281
 282     InsertAfter (me : in out; I : Item;
 283                  It : in out ListIterator)
 284         ---Level: Public
 285         ---Purpose: Insert <I> in the List after the  current position
 286         -- if <It>. <It> is not changed.
 287     is static;
 288
 289     InsertAfter (me : in out; Other : in out List from TCollection;
 290                  It : in out ListIterator)
 291         ---Level: Public
 292         ---Purpose: Insert <Other> in the List after the  current position
 293         -- if <It>. <It> is not changed. <Other> is cleared.
 294     is static;
 295
 296 fields
 297     myFirst : Address from Standard;
 298     myLast  : Address from Standard;
 299
 300 friends
 301     class ListIterator from TCollection
 302
 303 end List;
 304
 305
 306