0025790: Drop unimplemented method ShallowCopy() from TCollection_HSequence.cdl
[occt.git] / src / TCollection / TCollection_HSequence.cdl
CommitLineData
b311480e 1-- Created on: 1992-11-26
2-- Created by: Mireille MERCIEN
3-- Copyright (c) 1992-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 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
973c2be1 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.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
17generic class HSequence from TCollection
18 (Item as any;
19 TheSequence as any) -- Sequence from TCollection(Item))
20inherits 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
43raises
44 NoSuchObject from Standard,
45 OutOfRange from Standard
46
47is
6e33d3ce 48 Create returns HSequence from TCollection;
7fd59977 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)
6e33d3ce 188 returns HSequence
7fd59977 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
7fd59977 273
7fd59977 274fields
275 mySequence : TheSequence;
276end;
277
278
279