[occt.git] / src / TCollection / TCollection_HSequence.cdl

-- File:	TCollection_HSequence.cdl
-- Created:	Thu Nov 26 19:33:29 1992
-- Author:	Mireille MERCIEN
--		<mip@sdsun3>
---Copyright:	 Matra Datavision 1992


generic class HSequence from TCollection 
    (Item as any;
     TheSequence as any) -- Sequence from TCollection(Item))  
inherits TShared from MMgt

    ---Purpose: A sequence of items indexed by an integer.
    -- Sequences have about the same goal as unidimensional
    -- arrays (TCollection_HArray1): they are commonly used
    -- as elementary data structures for more complex objects.
    -- But a sequence is a structure of variable size: sequences
    -- avoid the use of large and quasi-empty arrays. Exploring
    -- a sequence data structure is efficient when the exploration
    -- is done in sequence; elsewhere a sequence item takes
    -- longer to be read than an array item. Note also that
    -- sequences are not efficient when they have to support
    -- numerous algorithmic explorations: a map is better for that purpose.
    -- HSequence objects are handles to sequences.
    -- -   HSequence sequences may be shared by several objects.
    --  -   You may use a TCollection_Sequence structure to
    --  have the actual sequence.
    -- HSequence is a generic class which depends on two parameters:
    -- -   Item, the type of element in the sequence,
    -- -   Seq, the actual type of sequence handled by
    --   HSequence. This is an instantiation with Item of the
    --   TCollection_Sequence generic class.A

raises
    NoSuchObject from Standard,
    OutOfRange from Standard
    
is 
	Create returns mutable HSequence from TCollection;
		---Purpose: Constructs an empty sequence.
    	    	-- Use:
    	    	-- -   the function Append or Prepend to add an item or
    	    	--   a collection of items at the end, or at the beginning of   the sequence,
    	    	-- -   the function InsertAfter or InsertBefore to add an
    	    	--   item or a collection of items at any position in the sequence,
    	    	-- -   the function SetValue or ChangeValue to assign a
    	    	--   new value to an item of the sequence,
    	    	-- -   the function Value to read an item of the sequence,
    	    	-- -   the function Remove to remove an item at any position in the sequence.
		---C++: inline
		
	IsEmpty(me) returns Boolean;
		---Level: Public
		---Purpose: returns True if the sequence <me> contains no elements.
		---C++: inline
    

	Length(me)  returns Integer;
		---Level: Public
		---Purpose: Returns  the  number  of element(s) in the
		-- sequence.  Returns zero if the sequence is empty.
		--          
		---C++: inline

	Clear(me : mutable);
		---Level: Public
		---Purpose: Removes all element(s) of the sequence <me>
		-- Example:
		-- before
		--   me = (A B C)
		-- after
		--   me = ()

	Append(me : mutable; anItem : Item);
		---Level: Public
		---Purpose: Appends <anItem> at the end of <me>.
		-- Example:
		-- before
		--   me = (A B C)
		-- after
		--   me = (A B C anItem)

	Append(me : mutable; aSequence : HSequence);
		---Level: Public
		---Purpose: Concatenates <aSequence> at the end of <me>.
		-- Example:
		-- before
		--   me = (A B C)
		--   aSequence  = (D E F)
		-- after
		--   me = (A B C D E F)
		--   aSequence  = (D E F)
	

	Prepend(me : mutable; anItem : Item);
		---Level: Public
		---Purpose: Add <anItem> at the beginning of <me>.
		-- Example:
		-- before
		--   me = (A B C)
		-- after
		--   me = (anItem A B C )

	Prepend(me : mutable; aSequence : HSequence);
		---Purpose: Concatenates <aSequence> at the beginning of <me>.
		-- Example:
		-- before 
		-- me = (A B C) 
		-- aSequence =  (D E F)
		-- after me = (D E F A B C) 
		-- aSequence = (D E F)

	Reverse(me : mutable);
		---Purpose: Reverses the order of items on <me>.The first one becomes the last one and inversely.
		-- Example:
		-- before
		--   me = (A B C)
		-- after
		--   me = (C B A)

	InsertBefore(me : mutable; anIndex : Integer; anItem : Item) 
	raises OutOfRange from Standard;
		---Purpose: Inserts  <anItem> in  <me>  before the position <anIndex>.
		-- Raises an exception if the anIndex is out of bounds.
		-- Example:
		-- before
		--   me = (A B D), anIndex = 3, anItem = C
		-- after
		--   me = (A B C D )

	InsertBefore(me : mutable ; anIndex : Integer; aSequence : HSequence) 
	raises OutOfRange from Standard;
		---Purpose: Inserts the  sequence <aSequence>  in  <me> before
		-- the position <anIndex>.
		-- Raises an exception if the anIndex is out of bounds.
		-- Example:
		-- before
		--   me = (A B F), anIndex = 3, aSequence = (C D E)
		-- after
		--   me = (A B C D E F)
		--   aSequence  = (C D E)

	InsertAfter(me : mutable; anIndex : Integer; anItem : Item) 
	raises OutOfRange from Standard;
		---Purpose: Inserts  <anItem>  in  <me> after the  position
		--          <anIndex>.
		-- Raises an exception if anIndex is out of bound.
		-- Example:
		-- before
		--   me = (A B C), anIndex = 3, anItem = D
		-- after
		--   me = (A B C D)

	InsertAfter(me : mutable ; anIndex : Integer; aSequence : HSequence) 
	raises OutOfRange from Standard;
		---Purpose: Inserts the sequence  <aSequence> in  <me>
		-- after the position <anIndex>.
		-- Raises an exception if  anIndex is out of bound.
		-- Example:         
		-- before
		--   me = (A B C), anIndex = 3, aSequence = (D E F)
		-- after
		--   me = (A B C D E F)
		--   aSequence  = (D E F)

	Exchange(me : mutable; anIndex, anOtherIndex : Integer)
    	raises OutOfRange from Standard;
		---Purpose: Swaps   elements   which  are  located  at
		-- positions <anIndex>  and <anOtherIndex> in <me>.
		-- Raises  an exception if  anIndex or anOtherIndex is out of bound.
		-- Example:
		-- before
		--   me = (A B C), anIndex = 1, anOtherIndex = 3            
		-- after
		--   me = (C B A)           


	Split(me : mutable; anIndex : Integer) 
    	returns mutable HSequence 
        raises OutOfRange from Standard
		---Purpose: Keeps in <me> the items 1 to <anIndex>-1 and
		-- returns the items <anIndex> to the end.
		-- Example:
		--  before
		--   me = (A B C D) ,anIndex = 3
		-- after
		--   me  =   (A B)
		--   returns (C D)
	is static;

	SetValue(me : mutable; anIndex : Integer; anItem : Item) 
	raises OutOfRange from Standard
		---Purpose: Sets  <anItem> to  be   the item  at   position
		-- <anIndex> in <me>.
		-- Raises an exception if anIndex is out of bounds
	    	-- Example:
		-- before 
		--   me = (A B D), anIndex = 3, anItem = C
		-- after
		--   me = (A B C)
	is static;

	Value(me; anIndex : Integer) returns any Item 
    	raises OutOfRange from Standard
		---Purpose: Returns  the Item  at position <anIndex>  in <me>. 
		-- Raises an exception if the anIndex is out of bound
		-- Example:
		-- before 
		--   me = (A B C), anIndex = 1
		-- after
		--   me = (A B C)
		-- returns 
		--   A
		---C++: return const &
    	is static;

	ChangeValue(me : mutable; anIndex : Integer) returns any Item 
    	raises OutOfRange from Standard
		---Purpose: Returns  the Item  at position <anIndex>  in <me>. 
		-- Raises an exception if the anIndex is out of bound.
		-- Example:
		-- before 
		--   me = (A B C), anIndex = 1
		-- after
		--   me = (A B C)
		-- returns 
		--   A
		---C++: return &
    	is static;

	Remove(me : mutable; anIndex : Integer) 
    	raises OutOfRange from Standard;
		---Purpose: Removes  from  <me> the  item at  position
		-- <anIndex>.
		-- Raises an exception if anIndex is out of bounds.
    	    	-- Example:
		-- before
		--   me = (A B C), anIndex = 3
		-- after
		--   me = (A B)

	Remove(me : mutable; fromIndex, toIndex : Integer) 
      	raises OutOfRange from Standard;
		---Purpose: Removes  from  <me>    all  the  items  of
		-- positions between <fromIndex> and <toIndex>.
		-- Raises an exception if the indices are out of bounds.
		-- Example:
		-- before
		--   me = (A B C D E F), fromIndex = 1 toIndex = 3
		-- after
		--   me = (D E F)
	
	Sequence(me) returns TheSequence;
	    ---Purpose: Returns the Seq sequence used as a field by this
    	    -- sequence; the returned sequence is not modifiable;
	    ---C++: return const &
	    ---C++: inline

	ChangeSequence(me : mutable) returns TheSequence;
	    ---Purpose: -   Returns a modifiable reference on the Seq
    	    -- sequence used as a field by this sequence, in order to modify it.
	    ---C++: return &
	    ---C++: inline
  
        ShallowCopy(me) returns mutable like me;
            ---Purpose: function call  
	    ---C++: function call 

        -- IsSameState (me; other : like me)  returns Boolean;
   
fields 
  mySequence : TheSequence;
end;
Commit	Line	Data
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
	8	generic class HSequence from TCollection
	9	(Item as any;
	10	TheSequence as any) -- Sequence from TCollection(Item))
	11	inherits 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
	34	raises
	35	NoSuchObject from Standard,
	36	OutOfRange from Standard
	37
	38	is
	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
271	fields
272	mySequence : TheSequence;
273	end;
274
275
276