2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseColIListT.h
19 * @brief This is the header file for the %IListT interface.
21 * This header file contains the declarations of the %IListT interface.
23 #ifndef _FBASE_COL_ILIST_T_H_
24 #define _FBASE_COL_ILIST_T_H_
26 #include <FBaseColIBidirectionalEnumeratorT.h>
27 #include <FBaseColICollectionT.h>
28 #include <FBaseColIComparerT.h>
31 namespace Tizen { namespace Base { namespace Collection
36 * @brief This interface represents a template-based collection of objects that can be individually accessed by an index.
40 * The %IListT interface represents a template-based collection of objects that can be individually accessed by an index.
43 template< class Type >
45 : public virtual ICollectionT< Type >
49 * This polymorphic destructor should be overridden if required. @n
50 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
54 virtual ~IListT(void) {}
57 * Adds the specified object to the list.
61 * @return An error code
62 * @param[in] obj The object to add
63 * @exception E_SUCCESS The method is successful.
64 * @exception E_OUT_OF_MEMORY The memory is insufficient.
65 * @remarks In a collection of contiguous elements, such as a list, the elements
66 * that follow the insertion point move down to accommodate the new element.
67 * If the collection is indexed, the indexes of the elements that are moved
68 * are also updated. This behavior does not apply to collections where
69 * elements are conceptually grouped into buckets, such as a hashtable.
72 virtual result Add(const Type& obj) = 0;
75 * Adds the elements of the specified collection to the end of the list.
79 * @return An error code
80 * @param[in] collection The collection to add
81 * @exception E_SUCCESS The method is successful.
82 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
83 * the specified @c collection is modified during the operation of this method.
86 virtual result AddItems(const ICollectionT< Type >& collection) = 0;
89 * Searches for an object in this list. @n
90 * Gets the index of the object if found.
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 is not found.
100 virtual result IndexOf(const Type& obj, int& index) const = 0;
103 * Searches for an object starting from the specified index. @n
104 * Gets the index of the object if found.
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 The specified index is outside the bounds of the data structure, or
115 * the specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0.
116 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
119 virtual result IndexOf(const Type& obj, int startIndex, int& index) const = 0;
122 * Searches for an object within the specified range. @n
123 * Gets the index of the object if found.
127 * @return An error code
128 * @param[in] obj The object to locate
129 * @param[in] startIndex The starting index of the range
130 * @param[in] count The number of elements to read
131 * @param[out] index The index of the object
132 * @exception E_SUCCESS The method is successful.
133 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
134 * - The specified index is outside the bounds of the data structure. @n
135 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
136 * - The @c count is greater than the number of elements starting from @c startIndex
138 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
141 virtual result IndexOf(const Type& obj, int startIndex, int count, int& index) const = 0;
144 * Searches for the last occurrence of an object in this list. @n
145 * Gets the index of the object if found.
149 * @return An error code
150 * @param[in] obj The object to locate
151 * @param[out] index The index of the last occurrence of the specified object
152 * @exception E_SUCCESS The method is successful.
153 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
156 virtual result LastIndexOf(const Type& obj, int& index) const = 0;
159 * Inserts an object at the specified location in the list.
163 * @return An error code
164 * @param[in] obj The object to insert
165 * @param[in] index The index at which the object must be inserted
166 * @exception E_SUCCESS The method is successful.
167 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
168 * the @c index is greater than the number of elements in the list or less than @c 0.
169 * @remarks If the @c index equals the number of elements in the list, the new element
170 * is added at the end of the list.
174 virtual result InsertAt(const Type& obj, int index) = 0;
177 * Inserts the elements of a collection in the list at the specified location.
181 * @return An error code
182 * @param[in] collection The collection to insert
183 * @param[in] startIndex The starting index at which the collection must be inserted
184 * @exception E_SUCCESS The method is successful.
185 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
186 * the @c startIndex is greater than the number of elements in the list or less than @c 0.
187 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
188 * the specified @c collection is modified during the operation of this method.
189 * @remarks If the @c startIndex equals the number of elements in the list, the new elements
190 * are added at the end of the list.
194 virtual result InsertItemsFrom(const ICollectionT< Type >& collection, int startIndex) = 0;
197 * Gets the object at the specified location.
201 * @return An error code
202 * @param[in] index The index of the object to get
203 * @param[out] obj The object obtained from the list
204 * @exception E_SUCCESS The method is successful.
205 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
206 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
209 virtual result GetAt(int index, Type& obj) const = 0;
212 * Gets the object at the specified location.
216 * @return An error code
217 * @param[in] index The index of the object to get
218 * @param[out] obj The object obtained from the list
219 * @exception E_SUCCESS The method is successful.
220 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
221 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
224 virtual result GetAt(int index, Type& obj) = 0;
227 * Gets all the elements of the list within the specified range.
231 * @return A pointer to %IListT with elements lying within the specified range, @n
232 * else @c null if an exception occurs
233 * @param[in] startIndex The starting index of the range
234 * @param[in] count The number of elements to read
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
237 * - The specified index is outside the bounds of the data structure. @n
238 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
239 * - The @c count is greater than the number of elements in the list starting from @c startIndex
241 * @remarks The specific error code can be accessed using the GetLastResult() method.
243 virtual IListT< Type >* GetItemsN(int startIndex, int count) const = 0;
246 * Removes the first occurrence of the specified object.
250 * @return An error code
251 * @param[in] obj The object to remove
252 * @exception E_SUCCESS The method is successful.
253 * @exception E_OBJ_NOT_FOUND The object is not found.
255 virtual result Remove(const Type& obj) = 0;
258 * Removes the object at the specified location.
262 * @return An error code
263 * @param[in] index The index at which the object must be removed
264 * @exception E_SUCCESS The method is successful.
265 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
266 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
268 virtual result RemoveAt(int index) = 0;
271 * Removes all the elements from the list that are common to the specified collection.
275 * @return An error code
276 * @param[in] collection The collection to remove from this list
277 * @exception E_SUCCESS The method is successful.
278 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
279 * the specified @c collection is modified during the operation of this method.
283 virtual result RemoveItems(const ICollectionT< Type >& collection) = 0;
286 * Removes all the elements within the specified range.
290 * @return An error code
291 * @param[in] startIndex The starting index of the range
292 * @param[in] count The number of elements in the range
293 * @exception E_SUCCESS The method is successful.
294 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
295 * - The specified index is outside the bounds of the data structure. @n
296 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
297 * - The @c count is greater than the number of elements starting from @c startIndex
300 * @see InsertItemsFrom()
302 virtual result RemoveItems(int startIndex, int count) = 0;
305 * Removes all the elements in the list.
309 virtual void RemoveAll(void) = 0;
312 * Sets the object at the specified index with the specified object.
316 * @return An error code
317 * @param[in] obj The new object
318 * @param[in] index The index at which the new object must be set
319 * @exception E_SUCCESS The method is successful.
320 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
321 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
324 virtual result SetAt(const Type& obj, int index) = 0;
327 * Sorts the elements of this list using the comparer provided.
331 * @return An error code
332 * @param[in] comparer The IComparerT implementation to use when comparing elements
333 * @exception E_SUCCESS The method is successful.
334 * @exception E_INVALID_ARG The specified input parameter is invalid.
336 virtual result Sort(const IComparerT< Type >& comparer) = 0;
339 * Checks whether the list contains the specified object.
343 * @return @c true if the list contains the specified object, @n
345 * @param[in] obj The object to locate
347 virtual bool Contains(const Type& obj) const = 0;
350 * Checks whether the list contains all the elements of the specified collection.
354 * @return An error code
355 * @param[in] collection The collection to check for containment in this list
356 * @param[out] out Set to @c true if the list contains all the elements of the specified collection, @n
358 * @exception E_SUCCESS The method is successful.
359 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
360 * the specified @c collection is modified during the operation of this method.
361 * @remarks If the given @c collection is empty, the @c out parameter is set to @c true.
364 virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const = 0;
367 * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class) of this list.
371 * @return A pointer to a bidirectional enumerator interface of the %IListT derived class, @n
372 * else @c null if an exception occurs
373 * @exception E_SUCCESS The method is successful.
374 * @exception E_OUT_OF_MEMORY The memory is insufficient.
375 * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class)
376 * to iterate over a collection (an instance of the %IListT derived class).
377 * @remarks The specific error code can be accessed using the GetLastResult() method.
378 * @see Tizen::Base::Collection::IBidirectionalEnumeratorT
380 virtual IBidirectionalEnumeratorT< Type >* GetBidirectionalEnumeratorN(void) const = 0;
384 }}} // Tizen::Base::Collection
386 #endif // _FBASE_COL_ILIST_T_H_