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