b767a17c9afb96ee61a128252efcd84bf54ea8d3
[occt.git] / 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 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 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 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 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 fields 
275   mySequence : TheSequence;
276 end;
277
278
279