src/TCollection/TCollection_Sequence.cdl

   1 -- Created on: 1992-09-11
   2 -- Created by: Mireille MERCIEN
   3 -- Copyright (c) 1992-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22
  23 generic class Sequence from TCollection (SeqItem as any)
  24 inherits BaseSequence from TCollection
  25
  26         ---Purpose: A sequence of items indexed by an integer.
  27         -- Sequences have approximately the same goal as
  28         -- unidimensional arrays (TCollection_Array1): they are
  29         -- commonly used as elementary data structures for more
  30         -- complex objects. But a sequence is a structure of
  31         -- variable size: sequences avoid the use of large and
  32         -- quasi-empty arrays. Exploring a sequence data
  33         -- structure is performant when the exploration is done in
  34         -- sequence; elsewhere a sequence item is longer to read
  35         -- than an array item. Note also that sequences are not
  36         -- performant when they have to support numerous
  37         -- algorithmic explorations: a map is better for that.
  38         -- Sequence is a generic class which depends on Item,
  39         -- the type of element in the sequence.
  40 raises
  41
  42     NoSuchObject from Standard,
  43     OutOfRange from Standard
  44
  45     class SequenceNode from TCollection
  46         inherits SeqNode from TCollection
  47         uses SeqNodePtr from TCollection
  48     is
  49         Create(I : SeqItem; n,p : SeqNodePtr from TCollection) returns SequenceNode from TCollection;
  50         ---C++: inline
  51
  52         Value(me) returns SeqItem;
  53         ---C++: return &
  54         ---C++: inline
  55
  56         fields
  57             myValue : SeqItem;
  58     end;
  59
  60 is
  61
  62         Create returns  Sequence;
  63                 ---Purpose: Constructs an empty sequence.
  64                 -- Use:
  65                 -- -   the function Append or Prepend to add an item or
  66                 -- a collection of items at the end, or at the beginning of the sequence,
  67                 -- -   the function InsertAfter or InsertBefore to add an
  68                 -- item or a collection of items at any position in the sequence,
  69                 -- -   operator() or the function SetValue to assign a
  70                 --   new value to an item of the sequence,
  71                 -- -   operator() to read an item of the sequence,
  72                 -- -   the function Remove to remove an item at any
  73                 --   position in the sequence.
  74                 --   Warning
  75                 -- To copy a sequence, you must explicitly call the
  76                 -- assignment operator (operator=).
  77                 ---C++: inline
  78
  79         Create(Other : Sequence) returns Sequence from TCollection
  80                 ---Purpose: Creation by copy of existing Sequence.
  81                 --  Warning: This constructor prints a warning message.
  82                 -- We recommand to use the operator =.
  83         is private;
  84
  85         Clear(me : in out);
  86                 ---Purpose: Removes all element(s) of the sequence <me>
  87                 --  Example:
  88                 -- before
  89                 --   me = (A B C)
  90                 -- after
  91                 --   me = ()
  92                 --
  93                 ---C++: alias ~
  94
  95         Assign(me : in out; Other : Sequence) returns Sequence from TCollection
  96                 ---Purpose: Copies the contents of the sequence Other into this sequence.
  97                 -- If this sequence is not empty, it is automatically cleared before the copy.
  98                 ---C++: alias operator =
  99                 ---C++: return const &
 100         is static;
 101
 102         Append(me : in out; T : SeqItem);
 103                 ---Level: Public
 104                 ---Purpose: Appends <T> at the end of <me>.
 105                 --  Example:
 106                 -- before
 107                 --   me = (A B C)
 108                 -- after
 109                 --   me = (A B C T)
 110
 111         Append(me : in out; S : in out Sequence)
 112                 ---Level: Public
 113                 ---Purpose: Concatenates <S> at the end of <me>.
 114                 -- <S> is cleared.
 115                 --  Example:
 116                 -- before
 117                 --   me = (A B C)
 118                 --   S  = (D E F)
 119                 -- after
 120                 --   me = (A B C D E F)
 121                 --   S  = ()
 122                 --
 123                 ---C++: inline
 124         is static;
 125
 126         Prepend(me : in out; T : SeqItem);
 127                 ---Level: Public
 128                 ---Purpose: Add <T> at the beginning of <me>.
 129                 --  Example:
 130                 -- before
 131                 --   me = (A B C)
 132                 -- after
 133                 --   me = (T A B C )
 134
 135         Prepend(me : in out; S : in out Sequence);
 136                 ---Level: Public
 137                 ---Purpose: Concatenates <S> at the beginning of <me>.
 138                 -- <S> is cleared.
 139                 --  Example:
 140                 -- before
 141                 -- me = (A B C) S =  (D E F)
 142                 -- after me = (D E F A B C)
 143                 -- S = ()
 144                 --
 145                 ---C++: inline
 146
 147         InsertBefore(me : in out; Index : Integer from Standard; T : SeqItem)
 148         raises OutOfRange from Standard;
 149                 ---Level: Public
 150                 ---Purpose: Inserts  <T> in  <me>  before the position <Index>.
 151                 -- Raises an exception if the index is out of bounds.
 152                 --  Example:
 153                 -- before
 154                 --   me = (A B D), Index = 3, T = C
 155                 -- after
 156                 --   me = (A B C D )
 157                 --
 158                 ---C++: inline
 159
 160         InsertBefore(me : in out ; Index : Integer from Standard; S : in out Sequence)
 161         raises OutOfRange from Standard;
 162                 ---Level: Public
 163                 ---Purpose: Inserts the  sequence <S>  in  <me> before
 164                 -- the position <Index>. <S> is cleared.
 165                 -- Raises an exception if the index is out of bounds
 166                 --  Example:
 167                 -- before
 168                 --   me = (A B F), Index = 3, S = (C D E)
 169                 -- after
 170                 --   me = (A B C D E F)
 171                 --   S  = ()
 172                 --
 173                 ---C++: inline
 174
 175         InsertAfter(me : in out; Index : Integer from Standard; T : SeqItem)
 176         raises OutOfRange from Standard;
 177                 ---Level: Public
 178                 ---Purpose: Inserts  <T>  in  <me> after the  position <Index>.
 179                 -- Raises an exception if the index is out of bound
 180                 --  Example:
 181                 -- before
 182                 --   me = (A B C), Index = 3, T = D
 183                 -- after
 184                 --   me = (A B C D)
 185
 186         InsertAfter(me : in out; Index : Integer from Standard; S : in out Sequence)
 187         raises OutOfRange from Standard;
 188                 ---Level: Public
 189                 ---Purpose: Inserts the sequence <S> in <me> after the
 190                 -- position <Index>. <S> is cleared.
 191                 -- Raises an exception if the index is out of bound.
 192                 --  Example:
 193                 -- before
 194                 --   me = (A B C), Index = 3, S = (D E F)
 195                 -- after
 196                 --   me = (A B C D E F)
 197                 --   S  = ()
 198                 --
 199                 ---C++: inline
 200
 201         First(me) returns any SeqItem
 202         raises NoSuchObject from Standard
 203                 ---Level: Public
 204                 ---Purpose: Returns the first element of the sequence <me>
 205                 -- Raises an exception if the sequence is empty.
 206                 --  Example:
 207                 -- before
 208                 --   me = (A B C)
 209                 -- after
 210                 --   me = (A B C)
 211                 -- returns A
 212                 ---C++: return const &
 213         is static;
 214
 215         Last(me)  returns  any SeqItem
 216         raises NoSuchObject from Standard
 217                 ---Level: Public
 218                 ---Purpose: Returns the last element of the sequence <me>
 219                 -- Raises an exception if the sequence is empty.
 220                 --  Example:
 221                 -- before
 222                 --   me = (A B C)
 223                 -- after
 224                 --   me = (A B C)
 225                 -- returns C
 226                 ---C++: return const &
 227         is static;
 228
 229         Split(me : in out; Index : Integer from Standard; Sub : in out Sequence)
 230         raises OutOfRange from Standard;
 231                 ---Level: Public
 232                 ---Purpose: Keeps in <me> the items 1 to <Index>-1 and
 233                 -- puts  in  <Sub> the  items <Index>  to the end.
 234                 --  Example:
 235                 -- before
 236                 --   me = (A B C D) ,Index = 3
 237                 -- after
 238                 --   me  = (A B)
 239                 --   Sub = (C D)
 240                 --
 241                 ---C++: inline
 242
 243         Value(me; Index : Integer from Standard) returns any SeqItem
 244         raises OutOfRange from Standard;
 245                 ---Level: Public
 246                 ---Purpose: Returns  the Item  at position <Index>  in <me>.
 247                 -- Raises an exception if the index is out of bound
 248                 --  Example:
 249                 -- before
 250                 --   me = (A B C), Index = 1
 251                 -- after
 252                 --   me = (A B C)
 253                 -- returns
 254                 --   A
 255                 ---C++: return const &
 256                 ---C++: alias operator()
 257
 258         SetValue(me : in out; Index : Integer from Standard; I : SeqItem)
 259         raises OutOfRange from Standard;
 260                 ---Level: Public
 261                 ---Purpose: Changes the item at position <Index>
 262                 -- Raises an exception if the index is out of bound
 263                 --  Example:
 264                 -- before
 265                 --   me = (A B C), Index = 1, Item = D
 266                 -- after
 267                 --   me = (D B C)
 268                 --
 269
 270         ChangeValue(me : in out; Index : Integer from Standard) returns any SeqItem
 271         raises OutOfRange from Standard;
 272                 ---Level: Public
 273                 ---Purpose: Returns  the Item  at position <Index>  in
 274                 -- <me>. This method  may  be  used to modify
 275                 -- <me> : S.Value(Index) = Item.
 276                 -- Raises an exception if the index is out of bound
 277                 --  Example:
 278                 -- before
 279                 --   me = (A B C), Index = 1
 280                 -- after
 281                 --   me = (A B C)
 282                 -- returns
 283                 --   A
 284                 ---C++: return &
 285                 ---C++: alias operator()
 286
 287         Remove(me : in out; Index : Integer from Standard)
 288         raises OutOfRange from Standard;
 289                 ---Level: Public
 290                 ---Purpose: Removes  from  <me> the  item at  position <Index>.
 291                 -- Raises an exception if the index is out of bounds
 292                 --  Example:
 293                 -- before
 294                 --   me = (A B C), Index = 3
 295                 -- after
 296                 --   me = (A B)
 297
 298         Remove(me : in out; FromIndex, ToIndex : Integer from Standard)
 299         raises OutOfRange from Standard;
 300                 ---Level: Public
 301                 ---Purpose: Removes  from  <me>    all  the  items  of
 302                 -- positions between <FromIndex> and <ToIndex>.
 303                 -- Raises an exception if the indices are out of bounds.
 304                 --  Example:
 305                 -- before
 306                 --   me = (A B C D E F), FromIndex = 1 ToIndex = 3
 307                 -- after
 308                 --   me = (D E F)
 309
 310 end;
 311
 312
 313