[2.2.1] Apply reviewed header file (Base to Collection)
[platform/framework/native/appfw.git] / inc / FBaseColIListT.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 // http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16
17 /**
18  * @file                FBaseColIListT.h
19  * @brief               This is the header file for the %IListT interface.
20  *
21  * This header file contains the declarations of the %IListT interface.
22  */
23 #ifndef _FBASE_COL_ILIST_T_H_
24 #define _FBASE_COL_ILIST_T_H_
25
26 #include <FBaseColIBidirectionalEnumeratorT.h>
27 #include <FBaseColICollectionT.h>
28 #include <FBaseColIComparerT.h>
29
30 namespace Tizen { namespace Base { namespace Collection
31 {
32
33 /**
34  * @interface   IListT
35  * @brief               This interface represents a template-based collection of objects that can be individually accessed by an index.
36  *
37  * @since 2.0
38  *
39  * The %IListT interface represents a template-based collection of objects that can be individually accessed by an index.
40  *
41  */
42 template< class Type >
43 class IListT
44         : public virtual ICollectionT< Type >
45 {
46 public:
47         /**
48          * This polymorphic destructor should be overridden if required. @n
49          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
50          *
51          * @since 2.0
52          */
53         virtual ~IListT(void) {}
54
55         /**
56          * Adds the specified object to the list.
57          *
58          * @since 2.0
59          *
60          * @return              An error code
61          * @param[in]   obj                             The object to add
62          * @exception   E_SUCCESS               The method is successful.
63          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
64          * @remarks             In a collection of contiguous elements, such as a list, the elements
65          *                              that follow the insertion point move down to accommodate the new element.
66          *                              If the collection is indexed, the indexes of the elements that are moved
67          *                              are also updated. This behavior does not apply to collections where
68          *                              elements are conceptually grouped into buckets, such as a hashtable.
69          * @see Remove()
70          */
71         virtual result Add(const Type& obj) = 0;
72
73         /**
74          * Adds the elements of the specified collection to the end of the list.
75          *
76          * @since 2.0
77          *
78          * @return              An error code
79          * @param[in]   collection                      The collection to add
80          * @exception   E_SUCCESS                       The method is successful.
81          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
82          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
83          *                                                                      - The specified @c collection is modified during the operation of this method.
84          * @see                 RemoveItems()
85          */
86         virtual result AddItems(const ICollectionT< Type >& collection) = 0;
87
88         /**
89          * Searches for an object in this list. @n
90          * Gets the @c index of the object if found.
91          *
92          * @since 2.0
93          *
94          * @return              An error code
95          * @param[in]   obj                                     The object to locate
96          * @param[out]  index                           The index of the object
97          * @exception   E_SUCCESS                       The method is successful.
98          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
99          */
100         virtual result IndexOf(const Type& obj, int& index) const = 0;
101
102         /**
103          * Searches for an object starting from the specified @c startIndex. @n
104          * Gets the @c index of the object if found.
105          *
106          * @since 2.0
107          *
108          * @return              An error code
109          * @param[in]   obj                             The object to locate
110          * @param[in]   startIndex                              The starting index for the search @n
111          *                                                                              It must be less than the number of elements.
112          * @param[out]  index                                   The index of the object
113          * @exception   E_SUCCESS                               The method is successful.
114          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
115          *                                                                              - The specified @c index is outside the bounds of the data structure.
116          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
117          *                                                                              - The specified @c startIndex is less than @c 0.
118          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
119          * @see                 LastIndexOf()
120          */
121         virtual result IndexOf(const Type& obj, int startIndex, int& index) const = 0;
122
123         /**
124          * Searches for an object within the specified range. @n
125          * Gets the @c index of the object if found.
126          *
127          * @since 2.0
128          *
129          * @return              An error code
130          * @param[in]   obj                             The object to locate
131          * @param[in]   startIndex                              The starting index of the range
132          * @param[in]   count                                   The number of elements to read
133          * @param[out]  index                                   The index of the object
134          * @exception   E_SUCCESS                               The method is successful.
135          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
136          *                                                                              - The specified @c index is outside the bounds of the data structure.
137          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
138          *                                                                              - The specified @c startIndex is less than @c 0.
139          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
140          *                                                                              - The specified @c count is less than @c 0.
141          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
142          * @see                 LastIndexOf()
143          */
144         virtual result IndexOf(const Type& obj, int startIndex, int count, int& index) const = 0;
145
146         /**
147          * Searches for the last occurrence of an object in this list. @n
148          * Gets the @c index of the object if found.
149          *
150          * @since 2.0
151          *
152          * @return              An error code
153          * @param[in]   obj                     The object to locate
154          * @param[out]  index                           The index of the last occurrence of the specified object
155          * @exception   E_SUCCESS                       The method is successful.
156          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
157          * @see                 IndexOf()
158          */
159         virtual result LastIndexOf(const Type& obj, int& index) const = 0;
160
161         /**
162          * Inserts an object at the specified location in the list.
163          *
164          * @since 2.0
165          *
166          * @return              An error code
167          * @param[in]   obj                                             The object to insert
168          * @param[in]   index                                   The index at which the object is inserted
169          * @exception   E_SUCCESS                               The method is successful.
170          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
171          *                                                                              - The specified @c index is outside the bounds of the data structure.
172          *                                                                              - The specified @c index is greater than the number of elements in the list.
173          *                                                                              - The specified @c index is less than @c 0.
174          * @remarks             If the @c index is equal to the number of elements in the list, the new element
175          *                              is added at the end of the list.
176          * @see                 Add()
177          * @see                 RemoveAt()
178          */
179         virtual result InsertAt(const Type& obj, int index) = 0;
180
181         /**
182          * Inserts the elements of a collection at the specified location in the list.
183          *
184          * @since 2.0
185          *
186          * @return              An error code
187          * @param[in]   collection                              The collection to insert
188          * @param[in]   startIndex                              The starting index at which the collection is inserted
189          * @exception   E_SUCCESS                               The method is successful.
190          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
191          *                                                                              - The specified @c index is outside the bounds of the data structure.
192          *                                                                              - The specified @c startIndex is greater than the number of elements in the list.
193          *                                                                              - The specified @c startIndex is less than @c 0.
194          * @exception   E_INVALID_OPERATION             Either of the following conditions has occurred:
195          *                                                                              - The current state of the instance prohibits the execution of the specified operation.
196          *                                                                              - The specified @c collection is modified during the operation of this method.
197          * @remarks             If the @c startIndex equals the number of elements in the list, the new elements
198          *                              are added at the end of the list.
199          * @see                 RemoveItems()
200          * @see                 AddItems()
201          */
202         virtual result InsertItemsFrom(const ICollectionT< Type >& collection, int startIndex) = 0;
203
204         /**
205          * Gets the object at the specified location.
206          *
207          * @since 2.0
208          *
209          * @return              An error code
210          * @param[in]   index                                   The index of the object to get
211          * @param[out]  obj                                             The object obtained from the list
212          * @exception   E_SUCCESS                               The method is successful.
213          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
214          *                                                                              - The specified @c index is outside the bounds of the data structure.
215          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
216          *                                                                              - The specified @c index is less than @c 0.
217          * @see                 SetAt()
218          */
219         virtual result GetAt(int index, Type& obj) const = 0;
220
221         /**
222          * Gets the object at the specified location.
223          *
224          * @since 2.0
225          *
226          * @return              An error code
227          * @param[in]   index                                   The index of the object to get
228          * @param[out]  obj                                             The object obtained from the list
229          * @exception   E_SUCCESS                               The method is successful.
230          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
231          *                                                                              - The specified @c index is outside the bounds of the data structure.
232          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
233          *                                                                              - The specified @c index is less than @c 0.
234          * @see                 SetAt()
235          */
236         virtual result GetAt(int index, Type& obj) = 0;
237
238         /**
239          * Gets all the elements of the list within the specified range.
240          *
241          * @since 2.0
242          *
243          * @return              A pointer to %IListT that contains the elements lying within the specified range, @n
244          *                              else @c null if an exception occurs
245          * @param[in]   startIndex                              The starting index of the range
246          * @param[in]   count                                   The number of elements to read
247          * @exception   E_SUCCESS                               The method is successful.
248          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
249          *                                                                              - The specified @c index is outside the bounds of the data structure.
250          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
251          *                                                                              - The specified @c startIndex is less than @c 0.
252          *                                                                              - The specified @c count is greater than the number of elements in the list starting from @c startIndex.
253          *                                                                              - The specified @c count is less than @c 0.
254          * @remarks             The specific error code can be accessed using the GetLastResult() method.
255          */
256         virtual IListT< Type >* GetItemsN(int startIndex, int count) const = 0;
257
258         /**
259          * Removes the first occurrence of the specified object.
260          *
261          * @since 2.0
262          *
263          * @return              An error code
264          * @param[in]   obj                                     The object to remove
265          * @exception   E_SUCCESS                       The method is successful.
266          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
267          */
268         virtual result Remove(const Type& obj) = 0;
269
270         /**
271          * Removes the object at the specified location.
272          *
273          * @since 2.0
274          *
275          * @return              An error code
276          * @param[in]   index                                   The index at which the object is removed
277          * @exception   E_SUCCESS                               The method is successful.
278          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
279          *                                                                              - The specified @c index is outside the bounds of the data structure.
280          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
281          *                                                                              - The specified @c index is less than @c 0.
282          */
283         virtual result RemoveAt(int index) = 0;
284
285         /**
286          * Removes all the elements from the list that are common to the specified @c collection.
287          *
288          * @since 2.0
289          *
290          * @return              An error code
291          * @param[in]   collection                      The collection to remove from this list
292          * @exception   E_SUCCESS                       The method is successful.
293          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
294          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
295          *                                                                      - The specified @c collection is modified during the operation of this method.
296          * @see                 Remove()
297          * @see                 RemoveAt()
298          */
299         virtual result RemoveItems(const ICollectionT< Type >& collection) = 0;
300
301         /**
302          * Removes all the elements within the specified range.
303          *
304          * @since 2.0
305          *
306          * @return              An error code
307          * @param[in]   startIndex                              The starting index of the range
308          * @param[in]   count                                   The number of elements in the range
309          * @exception   E_SUCCESS                               The method is successful.
310          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
311          *                                                                              - The specified @c index is outside the bounds of the data structure.
312          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
313          *                                                                              - The specified @c startIndex is less than @c 0.
314          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
315          *                                                                              - The specified @c count is less than @c 0.
316          * @see                 AddItems()
317          * @see                 InsertItemsFrom()
318          */
319         virtual result RemoveItems(int startIndex, int count) = 0;
320
321         /**
322          * Removes all the elements from the list.
323          *
324          * @since 2.0
325          */
326         virtual void RemoveAll(void) = 0;
327
328         /**
329          * Sets the object at the specified @c index with the specified object.
330          *
331          * @since 2.0
332          *
333          * @return              An error code
334          * @param[in]   obj                                             The new object
335          * @param[in]   index                                   The index at which the new object is set
336          * @exception   E_SUCCESS                               The method is successful.
337          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
338          *                                                                              - The specified @c index is outside the bounds of the data structure.
339          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
340          *                                                                              - The specified @c index is less than @c 0.
341          * @see                 GetAt()
342          */
343         virtual result SetAt(const Type& obj, int index) = 0;
344
345         /**
346          * Sorts the elements of this list using the @c comparer provided.
347          *
348          * @since 2.0
349          *
350          * @return              An error code
351          * @param[in]   comparer                The IComparerT implementation to use when comparing the elements
352          * @exception   E_SUCCESS               The method is successful.
353          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
354          */
355         virtual result Sort(const IComparerT< Type >& comparer) = 0;
356
357         /**
358          * Checks whether the list contains the specified object.
359          *
360          * @since 2.0
361          *
362          * @return              @c true if the list contains the specified object, @n
363          *                              else @c false
364          * @param[in]   obj     The object to locate
365          */
366         virtual bool Contains(const Type& obj) const = 0;
367
368         /**
369          * Checks whether the list contains all the elements of the specified @c collection.
370          *
371          * @since 2.0
372          *
373          * @return              An error code
374          * @param[in]   collection                      The collection to check for containment in this list
375          * @param[out]  out                                     Set to @c true if the list contains all the elements of the specified collection, @n
376          *                                                                      else @c false
377          * @exception   E_SUCCESS                       The method is successful.
378          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
379          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
380          *                                                                      - The specified @c collection is modified during the operation of this method.
381          * @remarks             If the given @c collection is empty, then @c out is set to @c true.
382          * @see                 Contains()
383          */
384         virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const = 0;
385
386         /**
387          * Gets the bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class) of this list.
388          *
389          * @since 2.0
390          *
391          * @return              A pointer to the bidirectional enumerator interface of the %IListT derived class, @n
392          *                              else @c null if an exception occurs
393          * @exception   E_SUCCESS                       The method is successful.
394          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
395          * @remarks
396          *                              - Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class)
397          *                              to iterate over a collection (an instance of the %IListT derived class).
398          *                              - The specific error code can be accessed using the GetLastResult() method.
399          */
400         virtual IBidirectionalEnumeratorT< Type >* GetBidirectionalEnumeratorN(void) const = 0;
401
402 }; // IListT
403
404 }}} // Tizen::Base::Collection
405
406 #endif // _FBASE_COL_ILIST_T_H_