src/TCollection/TCollection_HSequence.cdl

   1 -- Created on: 1992-11-26
   2 -- Created by: Mireille MERCIEN
   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
   9 -- under the terms of the GNU Lesser General Public 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 HSequence from TCollection
  18     (Item as any;
  19      TheSequence as any) -- Sequence from TCollection(Item))
  20 inherits TShared from MMgt
  21
  22     ---Purpose: A sequence of items indexed by an integer.
  23     -- Sequences have about the same goal as unidimensional
  24     -- arrays (TCollection_HArray1): they are commonly used
  25     -- as elementary data structures for more complex objects.
  26     -- But a sequence is a structure of variable size: sequences
  27     -- avoid the use of large and quasi-empty arrays. Exploring
  28     -- a sequence data structure is efficient when the exploration
  29     -- is done in sequence; elsewhere a sequence item takes
  30     -- longer to be read than an array item. Note also that
  31     -- sequences are not efficient when they have to support
  32     -- numerous algorithmic explorations: a map is better for that purpose.
  33     -- HSequence objects are handles to sequences.
  34     -- -   HSequence sequences may be shared by several objects.
  35     --  -   You may use a TCollection_Sequence structure to
  36     --  have the actual sequence.
  37     -- HSequence is a generic class which depends on two parameters:
  38     -- -   Item, the type of element in the sequence,
  39     -- -   Seq, the actual type of sequence handled by
  40     --   HSequence. This is an instantiation with Item of the
  41     --   TCollection_Sequence generic class.A
  42
  43 raises
  44     NoSuchObject from Standard,
  45     OutOfRange from Standard
  46
  47 is
  48         Create returns mutable HSequence from TCollection;
  49                 ---Purpose: Constructs an empty sequence.
  50                 -- Use:
  51                 -- -   the function Append or Prepend to add an item or
  52                 --   a collection of items at the end, or at the beginning of   the sequence,
  53                 -- -   the function InsertAfter or InsertBefore to add an
  54                 --   item or a collection of items at any position in the sequence,
  55                 -- -   the function SetValue or ChangeValue to assign a
  56                 --   new value to an item of the sequence,
  57                 -- -   the function Value to read an item of the sequence,
  58                 -- -   the function Remove to remove an item at any position in the sequence.
  59                 ---C++: inline
  60
  61         IsEmpty(me) returns Boolean;
  62                 ---Level: Public
  63                 ---Purpose: returns True if the sequence <me> contains no elements.
  64                 ---C++: inline
  65
  66
  67         Length(me)  returns Integer;
  68                 ---Level: Public
  69                 ---Purpose: Returns  the  number  of element(s) in the
  70                 -- sequence.  Returns zero if the sequence is empty.
  71                 --
  72                 ---C++: inline
  73
  74         Clear(me : mutable);
  75                 ---Level: Public
  76                 ---Purpose: Removes all element(s) of the sequence <me>
  77                 -- Example:
  78                 -- before
  79                 --   me = (A B C)
  80                 -- after
  81                 --   me = ()
  82
  83         Append(me : mutable; anItem : Item);
  84                 ---Level: Public
  85                 ---Purpose: Appends <anItem> at the end of <me>.
  86                 -- Example:
  87                 -- before
  88                 --   me = (A B C)
  89                 -- after
  90                 --   me = (A B C anItem)
  91
  92         Append(me : mutable; aSequence : HSequence);
  93                 ---Level: Public
  94                 ---Purpose: Concatenates <aSequence> at the end of <me>.
  95                 -- Example:
  96                 -- before
  97                 --   me = (A B C)
  98                 --   aSequence  = (D E F)
  99                 -- after
 100                 --   me = (A B C D E F)
 101                 --   aSequence  = (D E F)
 102
 103
 104         Prepend(me : mutable; anItem : Item);
 105                 ---Level: Public
 106                 ---Purpose: Add <anItem> at the beginning of <me>.
 107                 -- Example:
 108                 -- before
 109                 --   me = (A B C)
 110                 -- after
 111                 --   me = (anItem A B C )
 112
 113         Prepend(me : mutable; aSequence : HSequence);
 114                 ---Purpose: Concatenates <aSequence> at the beginning of <me>.
 115                 -- Example:
 116                 -- before
 117                 -- me = (A B C)
 118                 -- aSequence =  (D E F)
 119                 -- after me = (D E F A B C)
 120                 -- aSequence = (D E F)
 121
 122         Reverse(me : mutable);
 123                 ---Purpose: Reverses the order of items on <me>.The first one becomes the last one and inversely.
 124                 -- Example:
 125                 -- before
 126                 --   me = (A B C)
 127                 -- after
 128                 --   me = (C B A)
 129
 130         InsertBefore(me : mutable; anIndex : Integer; anItem : Item)
 131         raises OutOfRange from Standard;
 132                 ---Purpose: Inserts  <anItem> in  <me>  before the position <anIndex>.
 133                 -- Raises an exception if the anIndex is out of bounds.
 134                 -- Example:
 135                 -- before
 136                 --   me = (A B D), anIndex = 3, anItem = C
 137                 -- after
 138                 --   me = (A B C D )
 139
 140         InsertBefore(me : mutable ; anIndex : Integer; aSequence : HSequence)
 141         raises OutOfRange from Standard;
 142                 ---Purpose: Inserts the  sequence <aSequence>  in  <me> before
 143                 -- the position <anIndex>.
 144                 -- Raises an exception if the anIndex is out of bounds.
 145                 -- Example:
 146                 -- before
 147                 --   me = (A B F), anIndex = 3, aSequence = (C D E)
 148                 -- after
 149                 --   me = (A B C D E F)
 150                 --   aSequence  = (C D E)
 151
 152         InsertAfter(me : mutable; anIndex : Integer; anItem : Item)
 153         raises OutOfRange from Standard;
 154                 ---Purpose: Inserts  <anItem>  in  <me> after the  position
 155                 --          <anIndex>.
 156                 -- Raises an exception if anIndex is out of bound.
 157                 -- Example:
 158                 -- before
 159                 --   me = (A B C), anIndex = 3, anItem = D
 160                 -- after
 161                 --   me = (A B C D)
 162
 163         InsertAfter(me : mutable ; anIndex : Integer; aSequence : HSequence)
 164         raises OutOfRange from Standard;
 165                 ---Purpose: Inserts the sequence  <aSequence> in  <me>
 166                 -- after the position <anIndex>.
 167                 -- Raises an exception if  anIndex is out of bound.
 168                 -- Example:
 169                 -- before
 170                 --   me = (A B C), anIndex = 3, aSequence = (D E F)
 171                 -- after
 172                 --   me = (A B C D E F)
 173                 --   aSequence  = (D E F)
 174
 175         Exchange(me : mutable; anIndex, anOtherIndex : Integer)
 176         raises OutOfRange from Standard;
 177                 ---Purpose: Swaps   elements   which  are  located  at
 178                 -- positions <anIndex>  and <anOtherIndex> in <me>.
 179                 -- Raises  an exception if  anIndex or anOtherIndex is out of bound.
 180                 -- Example:
 181                 -- before
 182                 --   me = (A B C), anIndex = 1, anOtherIndex = 3
 183                 -- after
 184                 --   me = (C B A)
 185
 186
 187         Split(me : mutable; anIndex : Integer)
 188         returns mutable HSequence
 189         raises OutOfRange from Standard
 190                 ---Purpose: Keeps in <me> the items 1 to <anIndex>-1 and
 191                 -- returns the items <anIndex> to the end.
 192                 -- Example:
 193                 --  before
 194                 --   me = (A B C D) ,anIndex = 3
 195                 -- after
 196                 --   me  =   (A B)
 197                 --   returns (C D)
 198         is static;
 199
 200         SetValue(me : mutable; anIndex : Integer; anItem : Item)
 201         raises OutOfRange from Standard
 202                 ---Purpose: Sets  <anItem> to  be   the item  at   position
 203                 -- <anIndex> in <me>.
 204                 -- Raises an exception if anIndex is out of bounds
 205                 -- Example:
 206                 -- before
 207                 --   me = (A B D), anIndex = 3, anItem = C
 208                 -- after
 209                 --   me = (A B C)
 210         is static;
 211
 212         Value(me; anIndex : Integer) returns any Item
 213         raises OutOfRange from Standard
 214                 ---Purpose: Returns  the Item  at position <anIndex>  in <me>.
 215                 -- Raises an exception if the anIndex is out of bound
 216                 -- Example:
 217                 -- before
 218                 --   me = (A B C), anIndex = 1
 219                 -- after
 220                 --   me = (A B C)
 221                 -- returns
 222                 --   A
 223                 ---C++: return const &
 224         is static;
 225
 226         ChangeValue(me : mutable; anIndex : Integer) returns any Item
 227         raises OutOfRange from Standard
 228                 ---Purpose: Returns  the Item  at position <anIndex>  in <me>.
 229                 -- Raises an exception if the anIndex is out of bound.
 230                 -- Example:
 231                 -- before
 232                 --   me = (A B C), anIndex = 1
 233                 -- after
 234                 --   me = (A B C)
 235                 -- returns
 236                 --   A
 237                 ---C++: return &
 238         is static;
 239
 240         Remove(me : mutable; anIndex : Integer)
 241         raises OutOfRange from Standard;
 242                 ---Purpose: Removes  from  <me> the  item at  position
 243                 -- <anIndex>.
 244                 -- Raises an exception if anIndex is out of bounds.
 245                 -- Example:
 246                 -- before
 247                 --   me = (A B C), anIndex = 3
 248                 -- after
 249                 --   me = (A B)
 250
 251         Remove(me : mutable; fromIndex, toIndex : Integer)
 252         raises OutOfRange from Standard;
 253                 ---Purpose: Removes  from  <me>    all  the  items  of
 254                 -- positions between <fromIndex> and <toIndex>.
 255                 -- Raises an exception if the indices are out of bounds.
 256                 -- Example:
 257                 -- before
 258                 --   me = (A B C D E F), fromIndex = 1 toIndex = 3
 259                 -- after
 260                 --   me = (D E F)
 261
 262         Sequence(me) returns TheSequence;
 263             ---Purpose: Returns the Seq sequence used as a field by this
 264             -- sequence; the returned sequence is not modifiable;
 265             ---C++: return const &
 266             ---C++: inline
 267
 268         ChangeSequence(me : mutable) returns TheSequence;
 269             ---Purpose: -   Returns a modifiable reference on the Seq
 270             -- sequence used as a field by this sequence, in order to modify it.
 271             ---C++: return &
 272             ---C++: inline
 273
 274         ShallowCopy(me) returns mutable like me;
 275             ---Purpose: function call
 276             ---C++: function call
 277
 278         -- IsSameState (me; other : like me)  returns Boolean;
 279
 280 fields
 281   mySequence : TheSequence;
 282 end;
 283
 284
 285