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 FBaseColIList.h
19 * @brief This is the header file for the %IList interface.
21 * This header file contains the declarations of the %IList interface.
23 #ifndef _FBASE_COL_ILIST_H_
24 #define _FBASE_COL_ILIST_H_
26 #include <FBaseColIBidirectionalEnumerator.h>
27 #include <FBaseColICollection.h>
28 #include <FBaseColIComparer.h>
29 #include <FBaseColTypes.h>
30 #include <FBaseObject.h>
32 namespace Tizen { namespace Base { namespace Collection
37 * @brief This interface represents a collection of objects that can be individually accessed by an index.
41 * The %IList interface represents a collection of objects that can be individually accessed by an index.
44 class _OSP_EXPORT_ IList
45 : public virtual ICollection
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 ~IList(void) {}
58 * Adds the specified object to the list.
60 * @brief <i> [Deprecated] </i>
61 * @deprecated This method is deprecated because it has a problem of const reference argument.
62 * Instead of using this method, use Add(Object* pObj).
65 * @return An error code
66 * @param[in] obj The object to add
67 * @exception E_SUCCESS The method is successful.
68 * @exception E_OUT_OF_MEMORY The memory is insufficient.
69 * @remarks In a collection of contiguous elements, such as a list, the elements
70 * that follow the insertion point move down to accommodate the new element.
71 * If the collection is indexed, the indexes of the elements that are moved
72 * are also updated. This behavior does not apply to collections where
73 * elements are conceptually grouped into buckets, such as a hashtable.
74 * This method performs a shallow copy. It adds the pointer only; not the element itself.
78 result Add(const Object& obj)
80 return Add(const_cast< Object* >(&obj));
84 * Adds the specified object to the list.
88 * @return An error code
89 * @param[in] pObj The pointer to object to add
90 * @exception E_SUCCESS The method is successful.
91 * @exception E_INVALID_ARG The specified input parameter is invalid.
92 * @remarks In a collection of contiguous elements, such as a list, the elements
93 * that follow the insertion point move down to accommodate the new element.
94 * If the collection is indexed, the indexes of the elements that are moved
95 * are also updated. This behavior does not apply to collections where
96 * elements are conceptually grouped into buckets, such as a hashtable.
97 * This method performs a shallow copy. It adds the pointer only; not the element itself.
100 virtual result Add(Object* pObj) = 0;
103 * Adds the elements of the specified collection to the end of the list.
107 * @return An error code
108 * @param[in] collection The collection to add to the list
109 * @exception E_SUCCESS The method is successful.
110 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
111 * the specified @c collection is modified during the operation of this method.
112 * @remarks This method performs a shallow copy. It adds the pointer only; not the element itself.
115 virtual result AddItems(const ICollection& collection) = 0;
118 * Searches for an object in this list. @n
119 * Gets the index of the object if found.
123 * @return An error code
124 * @param[in] obj The object to locate
125 * @param[out] index The index of the object
126 * @exception E_SUCCESS The method is successful.
127 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
129 virtual result IndexOf(const Object& obj, int& index) const = 0;
133 * Inserts an object at the specified location in the list.
135 * @brief <i> [Deprecated] </i>
136 * @deprecated This method is deprecated because it has a problem of const reference argument.
137 * Instead of using this method, use InsertAt(const Object* pObj, int index).
140 * @return An error code
141 * @param[in] obj The object to insert
142 * @param[in] index The index at which the object must be inserted
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
145 * the @c index is greater than the number of elements in the list or less than @c 0.
146 * @remarks If the @c index equals the number of elements in the list, the new element
147 * is added at the end of the list.
148 * This method performs a shallow copy. It inserts the pointer only; not the element itself.
153 result InsertAt(const Object& obj, int index)
155 return InsertAt(const_cast< Object* >(&obj), index);
159 * Inserts an object at the specified location in the list.
163 * @return An error code
164 * @param[in] pObj The pointer to 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_INVALID_ARG The specified input parameter is invalid.
168 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
169 * the @c index is greater than the number of elements in the list or less than @c 0.
170 * @remarks If the @c index equals the number of elements in the list, the new element
171 * is added at the end of the list.
172 * This method performs a shallow copy. It inserts the pointer only; not the element itself.
176 virtual result InsertAt(Object* pObj, int index) = 0;
179 * Searches for an object starting from the specified index. @n
180 * Gets the index of the object if found.
184 * @return An error code
185 * @param[in] obj The object to locate
186 * @param[in] startIndex The starting index for the search @n
187 * It must be less than the number of elements.
188 * @param[out] index The index of the object
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
191 * the specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0.
192 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
195 virtual result IndexOf(const Object& obj, int startIndex, int& index) const = 0;
198 * Searches for an object within the specified range. @n
199 * Gets the index of the object if found.
203 * @return An error code
204 * @param[in] obj The object to locate
205 * @param[in] startIndex The starting index of the range
206 * @param[in] count The number of elements to read
207 * @param[out] index The index of the object
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
210 * - The specified index is outside the bounds of the data structure. @n
211 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
212 * - The @c count is greater than the number of elements starting from @c startIndex
214 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
217 virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const = 0;
220 * Searches for the last occurrence of an object in this list. @n
221 * Gets the index of the object if found.
225 * @return An error code
226 * @param[in] obj The object to locate
227 * @param[out] index The index of the last occurrence of the specified object
228 * @exception E_SUCCESS The method is successful.
229 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
232 virtual result LastIndexOf(const Object& obj, int& index) const = 0;
235 * Inserts the elements of a collection in the list at the specified location.
239 * @return An error code
240 * @param[in] collection The collection to insert
241 * @param[in] startIndex The starting index at which the collection must be inserted
242 * @exception E_SUCCESS The method is successful.
243 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
244 * the @c startIndex is greater than the number of elements in the list or less than @c 0.
245 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
246 * the specified @c collection is modified during the operation of this method.
247 * @remarks If the @c startIndex equals the number of elements in the list, the new elements
248 * are added at the end of the list.
249 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
253 virtual result InsertItemsFrom(const ICollection& collection, int startIndex) = 0;
256 * Gets the object at the specified location.
260 * @return The object at the specified location, @n
261 * else @c null if the @c index is not valid
262 * @param[in] index The index of the object to get
263 * @exception E_SUCCESS The method is successful.
264 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
265 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
266 * @remarks The specific error code can be accessed using the GetLastResult() method.
269 virtual const Object* GetAt(int index) const = 0;
272 * Gets the object at the specified location.
276 * @return The object at the specified location, @n
277 * else @c null if the @c index is not valid
278 * @param[in] index The index of the object to get
279 * @exception E_SUCCESS The method is successful.
280 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
281 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
282 * @remarks The specific error code can be accessed using the GetLastResult() method.
285 virtual Object* GetAt(int index) = 0;
288 * Gets all the elements of the list within the specified range.
292 * @return A pointer to an %IList with elements lying within the specified range, @n
293 * else @c null if an exception occurs
294 * @param[in] startIndex The starting index of the range
295 * @param[in] count The number of elements to read
296 * @exception E_SUCCESS The method is successful.
297 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
298 * - The specified index is outside the bounds of the data structure. @n
299 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
300 * - The @c count is greater than the number of elements in the list starting from @c startIndex
302 * @remarks The %IList stores just the pointers to the elements in the list, not the elements themselves.
303 * The specific error code can be accessed using the GetLastResult() method.
305 virtual IList* GetItemsN(int startIndex, int count) const = 0;
308 * Removes the first occurrence of the specified object.
312 * @return An error code
313 * @param[in] obj The object to remove
314 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
316 * @exception E_SUCCESS The method is successful.
317 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
318 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
319 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
320 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
321 * @remarks Remove(obj, @b true) internally works as the below code:
323 * DeleterFunctionType deleter = GetDeleter();
324 * SetDeleter(SingleObjectDeleter);
326 * SetDeleter(deleter);
328 * @remarks Remove(obj, @b false) internally works as the below code:
330 * DeleterFunctionType deleter = GetDeleter();
331 * SetDeleter(NoOpDeleter);
333 * SetDeleter(deleter);
338 result Remove(const Object& obj, bool forceDeletion)
340 DeleterFunctionType deleter = GetDeleter();
344 SetDeleter(SingleObjectDeleter);
348 SetDeleter(NoOpDeleter);
351 result r = Remove(obj);
357 * Removes the first occurrence of the specified object.
361 * @return An error code
362 * @param[in] obj The object to remove
363 * @exception E_SUCCESS The method is successful.
364 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
368 virtual result Remove(const Object& obj) = 0;
371 * Removes the object at the specified location.
375 * @return An error code
376 * @param[in] index The index at which the object must be removed
377 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
379 * @exception E_SUCCESS The method is successful.
380 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
381 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
382 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
383 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
384 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
385 * @remarks RemoveAt(index, @b true) internally works as the below code:
387 * DeleterFunctionType deleter = GetDeleter();
388 * SetDeleter(SingleObjectDeleter);
390 * SetDeleter(deleter);
392 * @remarks RemoveAt(index, @b false) internally works as the below code:
394 * DeleterFunctionType deleter = GetDeleter();
395 * SetDeleter(NoOpDeleter);
397 * SetDeleter(deleter);
400 result RemoveAt(int index, bool forceDeletion)
402 DeleterFunctionType deleter = GetDeleter();
406 SetDeleter(SingleObjectDeleter);
410 SetDeleter(NoOpDeleter);
413 result r = RemoveAt(index);
419 * Removes the object at the specified location.
423 * @return An error code
424 * @param[in] index The index at which the object must be removed
425 * @exception E_SUCCESS The method is successful.
426 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
427 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
429 virtual result RemoveAt(int index) = 0;
432 * Removes all the elements within the specified range.
436 * @return An error code
437 * @param[in] startIndex The starting index of the range
438 * @param[in] count The number of elements in the range
439 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
441 * @exception E_SUCCESS The method is successful.
442 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
443 * - The specified index is outside the bounds of the data structure. @n
444 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
445 * - The @c count is greater than the number of elements starting from @c startIndex
447 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
448 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
449 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
450 * @remarks RemoveItems(startIndex, count, @b true) internally works as the below code:
452 * DeleterFunctionType deleter = GetDeleter();
453 * SetDeleter(SingleObjectDeleter);
454 * RemoveItems(startIndex, count);
455 * SetDeleter(deleter);
457 * @remarks RemoveItems(startIndex, count, @b false) internally works as the below code:
459 * DeleterFunctionType deleter = GetDeleter();
460 * SetDeleter(NoOpDeleter);
461 * RemoveItems(startIndex, count);
462 * SetDeleter(deleter);
466 result RemoveItems(int startIndex, int count, bool forceDeletion)
468 DeleterFunctionType deleter = GetDeleter();
472 SetDeleter(SingleObjectDeleter);
476 SetDeleter(NoOpDeleter);
479 result r = RemoveItems(startIndex, count);
485 * Removes all the elements within the specified range.
489 * @return An error code
490 * @param[in] startIndex The starting index of the range
491 * @param[in] count The number of elements in the range
492 * @exception E_SUCCESS The method is successful.
493 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
494 * - The specified index is outside the bounds of the data structure. @n
495 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
496 * - The @c count is greater than the number of elements starting from @c startIndex
500 virtual result RemoveItems(int startIndex, int count) = 0;
503 * Removes all the elements from the list that are common to the specified collection.
507 * @return An error code
508 * @param[in] collection The collection to be removed from this list
509 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
511 * @exception E_SUCCESS The method is successful.
512 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
513 * the specified @c collection is modified during the operation of this method.
514 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
515 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
516 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
517 * @remarks RemoveItems(collection, @b true) internally works as the below code:
519 * DeleterFunctionType deleter = GetDeleter();
520 * SetDeleter(SingleObjectDeleter);
521 * RemoveItems(collection);
522 * SetDeleter(deleter);
524 * @remarks RemoveItems(collection, @b false) internally works as the below code:
526 * DeleterFunctionType deleter = GetDeleter();
527 * SetDeleter(NoOpDeleter);
528 * RemoveItems(collection);
529 * SetDeleter(deleter);
534 result RemoveItems(const ICollection& collection, bool forceDeletion)
536 DeleterFunctionType deleter = GetDeleter();
540 SetDeleter(SingleObjectDeleter);
544 SetDeleter(NoOpDeleter);
547 result r = RemoveItems(collection);
553 * Removes all the elements from the list that are common to the specified collection.
557 * @return An error code
558 * @param[in] collection The collection to remove from this list
559 * @exception E_SUCCESS The method is successful.
560 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
561 * the specified @c collection is modified during the operation of this method.
565 virtual result RemoveItems(const ICollection& collection) = 0;
568 * Removes all the object pointers in the collection. @n
569 * If the deallocate param is set to @c true, it removes all the objects in the collection. @n
570 * This method can be called just before deleting the collection.
574 * @return An error code
575 * @param[in] forceDeletion Set to @c true to deallocate all the objects, @n
577 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
578 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
579 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
580 * @remarks RemoveAll(@b true) internally works as the below code:
582 * DeleterFunctionType deleter = GetDeleter();
583 * SetDeleter(SingleObjectDeleter);
585 * SetDeleter(deleter);
587 * @remarks RemoveAll(@b false) internally works as the below code:
589 * DeleterFunctionType deleter = GetDeleter();
590 * SetDeleter(NoOpDeleter);
592 * SetDeleter(deleter);
595 void RemoveAll(bool forceDeletion)
597 DeleterFunctionType deleter = GetDeleter();
601 SetDeleter(SingleObjectDeleter);
605 SetDeleter(NoOpDeleter);
613 * Removes all the object pointers in the collection. @n
614 * This method can be called just before deleting the collection.
618 virtual void RemoveAll(void) = 0;
621 * Replaces the object at the specified index with the specified object.
625 * @return An error code
626 * @param[in] obj The new object
627 * @param[in] index The index at which the new object must be set
628 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
630 * @exception E_SUCCESS The method is successful.
631 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
632 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
633 * @remarks Based on the specified element deleter, the set operation not only gets rid of an element from a list, but also deletes its object instance. @n
634 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
635 * If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
636 * @remarks SetAt(obj, index, @b true) internally works as the below code:
638 * DeleterFunctionType deleter = GetDeleter();
639 * SetDeleter(SingleObjectDeleter);
640 * SetAt(const_cast< Object* >(&obj), index);
641 * SetDeleter(deleter);
643 * @remarks SetAt(obj, index, @b false) internally works as the below code:
645 * DeleterFunctionType deleter = GetDeleter();
646 * SetDeleter(NoOpDeleter);
647 * SetAt(const_cast< Object* >(&obj), index);
648 * SetDeleter(deleter);
652 result SetAt(const Object& obj, int index, bool forceDeletion = false)
654 DeleterFunctionType deleter = GetDeleter();
658 SetDeleter(SingleObjectDeleter);
662 SetDeleter(NoOpDeleter);
665 result r = SetAt(const_cast< Object* >(&obj), index);
671 * Replaces the object at the specified index with the specified object.
675 * @return An error code
676 * @param[in] pObj The pointer to new object
677 * @param[in] index The index at which the new object must be set
678 * @exception E_SUCCESS The method is successful.
679 * @exception E_INVALID_ARG The specified input parameter is invalid.
680 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
681 * the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
684 virtual result SetAt(Object* pObj, int index) = 0;
687 * Sorts the elements of this list using the comparer provided.
691 * @return An error code
692 * @param[in] comparer The IComparer implementation to use when comparing elements
693 * @exception E_SUCCESS The method is successful.
694 * @exception E_INVALID_ARG The specified input parameter is invalid.
696 virtual result Sort(const IComparer& comparer) = 0;
699 * Checks whether the list contains the specified object.
703 * @return @c true if the list contains the specified object, @n
705 * @param[in] obj The object to locate
707 virtual bool Contains(const Object& obj) const = 0;
711 * Checks whether the list contains all the elements of the specified collection.
713 * @brief <i> [Deprecated] </i>
714 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
715 * The return type will be changed into boolean type and this method will return the result.
716 * Instead of using this method, use bool ContainsAll(const ICollection& collection).
719 * @return An error code
720 * @param[in] collection The collection to check for containment in this list
721 * @param[out] out Set to @c true if the list contains all the elements of the specified collection, @n
723 * @exception E_SUCCESS The method is successful.
724 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
725 * the specified @c collection is modified during the operation of this method.
726 * @remarks If the given @c collection is empty, the @c out parameter is set to @c true.
730 result ContainsAll(const ICollection& collection, bool& out) const
732 out = ContainsAll(collection);
733 result r = GetLastResult();
738 * Checks whether the list contains all the elements of the specified collection.
742 * @return @c true if the list contains all the elements of the specified collection, @n
744 * @param[in] collection The collection to check for containment in this list
745 * @exception E_SUCCESS The method is successful.
746 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
747 * the specified @c collection is modified during the operation of this method.
748 * @remarks The specific error code can be accessed using the GetLastResult() method.
749 * @remarks If the given @c collection is empty, this method will return @c true.
752 virtual bool ContainsAll(const ICollection& collection) const = 0;
755 * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
759 * @return A pointer to a bidirectional enumerator interface of the %IList derived class, @n
760 * else @c null if an exception occurs
761 * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
762 * to iterate over a collection (an instance of the %IList derived class).
763 * The specific error code can be accessed using GetLastResult() method.
764 * @see Tizen::Base::Collection::IBidirectionalEnumerator
766 virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const = 0;
769 * This method is for distinguishing between ArrayList and LinkedList.
773 * @return @c true if it is an ArrayList, @n
774 * else @c false if it is a LinkedList.
776 virtual bool IsRandomAccessible(void) const
782 * Gets the element deleter of the collection.
786 * @return A function pointer to the existing element deleter
788 virtual DeleterFunctionType GetDeleter(void) const = 0;
792 // This method is for internal use only. Using this method can cause behavioral, security-related,
793 // and consistency-related issues in the application.
794 // This method is reserved and may change its name at any time without prior notice.
798 virtual void IList_Reserved1(void) {}
801 // This method is for internal use only. Using this method can cause behavioral, security-related,
802 // and consistency-related issues in the application.
803 // This method is reserved and may change its name at any time without prior notice.
807 virtual void IList_Reserved2(void) {}
811 * Sets the element deleter of the collection.
815 * @param[in] deleter A function pointer to the element deleter to set
817 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
821 }}} // Tizen::Base::Collection
823 #endif // _FBASE_COL_ILIST_H_