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 FBaseColLinkedList.h
19 * @brief This is the header file for the %LinkedList class.
21 * This header file contains the declarations of the %LinkedList class.
23 #ifndef _FBASE_COL_LINKED_LIST_H_
24 #define _FBASE_COL_LINKED_LIST_H_
26 #include <FBaseColIComparer.h>
27 #include <FBaseColIList.h>
29 namespace Tizen { namespace Base { namespace Collection
36 * @brief This class represents a collection of objects that can be individually accessed by index.
40 * The %LinkedList class represents a collection of objects that can be individually accessed by index.
42 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/arraylist_linkedlist.htm">ArrayList and LinkedList</a>.
44 * The following example demonstrates how to use the %LinkedList class.
49 * using namespace Tizen::Base;
50 * using namespace Tizen::Base::Collection;
53 * MyClass::LinkedListSample(void)
55 * LinkedList list(SingleObjectDeleter);
57 * list.Add(new Integer(1)); // 1
58 * list.Add(new Integer(2)); // 1,2
59 * list.Add(new Integer(3)); // 1,2,3
61 * Integer* pInt = static_cast< Integer* > (list.GetAt(0));
63 * if (pValue->Equals(Integer(1))
68 * list.InsertAt(new Integer(4), 1); // 1,4,2,3
70 * list.Remove(Integer(3)); // 1,4,2
72 * list.RemoveAt(0); // 4,2
74 * list.Sort(IntegerComparer()); // 2,4
76 * // Uses an enumerator to access elements in the list
77 * IEnumerator* pEnum = list.GetEnumeratorN();
78 * Object* pObj = null;
79 * while (pEnum->MoveNext() == E_SUCCESS)
81 * pObj = pEnum->GetCurrent();
86 * // Deallocates all objects
87 * // Because the destructor calls RemoveAll() internally, you do not need to call RemoveAll() to destroy all elements at the end.
88 * // list.RemoveAll();
92 class _OSP_EXPORT_ LinkedList
98 using IList::InsertAt;
100 using IList::RemoveAt;
101 using IList::RemoveItems;
102 using IList::RemoveAll;
104 using IList::ContainsAll;
106 * This is the default constructor for this class.
110 * @param[in] deleter The function pointer to type of the element deleter
111 * @remarks To create an owing collection, set the element deleter value as @c SingleObjectDeleter. This gives the collection the ownership of elements and the collection will destroy elements. @n
112 * On the other hand, to create a non-owning collection, you do not need to set the element deleter value, as @c NoOpDeleter is the default element deleter.
113 * It means that you do not transfer the ownership of elements to the collection.
115 * @see SingleObjectDeleter()
116 * @see ArrayDeleter()
118 explicit LinkedList(DeleterFunctionType deleter = NoOpDeleter);
121 * This destructor overrides Tizen::Base::Object::~Object().
125 virtual ~LinkedList(void);
128 * Adds the given object to the end of this list.
132 * @return An error code
133 * @param[in] pObj An pointer to object to add
134 * @exception E_SUCCESS The method is successful.
135 * @exception E_INVALID_ARG The specified input parameter is invalid.
136 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
139 virtual result Add(Object* pObj);
142 * Adds the elements of the given collection to the end of this list.
146 * @return An error code
147 * @param[in] collection A collection to add
148 * @exception E_SUCCESS The method is successful.
149 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
150 * the @c collection is modified during the operation of this method.
151 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
154 virtual result AddItems(const ICollection& collection);
157 * Gets an enumerator (an instance of the IEnumerator derived class) to the list.
161 * @return An enumerator of the calling list object, @n
162 * else @c null if an exception occurs
163 * @remarks The specific error code can be accessed using the GetLastResult() method.
164 * @see Tizen::Base::Collection::IEnumerator
166 virtual IEnumerator* GetEnumeratorN(void) const;
169 * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
173 * @return An instance of the IBidirectionalEnumerator derived class, @n
174 * else @c null if some exception occurs
175 * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
176 * to iterate over a collection (an instance of the IList derived class).
177 * The specific error code can be accessed using GetLastResult() method.
178 * @see Tizen::Base::Collection::IBidirectionalEnumerator
180 virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const;
183 * Gets the object at the specified index of the calling list.
187 * @return A pointer to the object at the specified index of the list, @n
188 * else @c null if the index is not valid
189 * @param[in] index The index of the object to read
190 * @exception E_SUCCESS The method is successful.
191 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
192 * the specified @c index is equal to or greater than the number of elements or less than @c 0.
193 * @remarks The specific error code can be accessed using the GetLastResult() method.
196 virtual const Object* GetAt(int index) const;
199 * Gets the object at the specified index of the calling list.
203 * @return A pointer to the object at the specified index of the list, @n
204 * else @c null if the index is not valid
205 * @param[in] index The index of the object to read
206 * @exception E_SUCCESS The method is successful.
207 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
208 * the specified @c index is equal to or greater than the number of elements or less than @c 0.
209 * @remarks The specific error code can be accessed using the GetLastResult() method.
212 virtual Object* GetAt(int index);
215 * Gets the reference of the object at the specified index of the calling list.
219 * @return The reference of the object at the specified index of the list
220 * @param[in] index The index of the object to read
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
223 * the specified @c index is equal to or greater than the number of elements or less than @c 0.
224 * @remarks The specific error code can be accessed using the GetLastResult() method.
226 virtual Object*& GetAtRef(int index);
229 * Gets an IList with the specified range from the calling list object.
233 * @return An IList pointer if successful, @n
234 * else @c null if an exception occurs
235 * @param[in] startIndex The starting index of the range
236 * @param[in] count The number of elements to read
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
239 * - The specified index is outside the bounds of the data structure. @n
240 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
241 * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0.
242 * @remarks The IList stores just the pointers to the elements in the list, not the elements themselves.
243 * The specific error code can be accessed using the GetLastResult() method.
245 virtual IList* GetItemsN(int startIndex, int count) const;
248 * Searches for an object in this list. @n
249 * Gets the index of the object if found.
253 * @return An error code
254 * @param[in] obj The object to locate
255 * @param[out] index The index of the object
256 * @exception E_SUCCESS The method is successful.
257 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
259 virtual result IndexOf(const Object& obj, int& index) const;
262 * Searches for an object starting from the specified index. @n
263 * Gets the index of the object if found.
267 * @return An error code
268 * @param[in] obj The object to locate
269 * @param[in] startIndex The starting index for the search @n
270 * It must be less than the number of elements.
271 * @param[out] index The index of the object
272 * @exception E_SUCCESS The method is successful.
273 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
274 * the specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0.
275 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
278 virtual result IndexOf(const Object& obj, int startIndex, int& index) const;
281 * Searches for an object within the specified range. @n
282 * Gets the index of the object if found.
286 * @return An error code
287 * @param[in] obj The object to locate
288 * @param[in] startIndex The starting index of the range
289 * @param[in] count The number of elements to read
290 * @param[out] index The index of the object
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
293 * - The specified index is outside the bounds of the data structure. @n
294 * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
295 * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0.
296 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
299 virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const;
302 * Searches for the last occurrence of an object in this list. @n
303 * Gets the index of the object if found.
307 * @return An error code
308 * @param[in] obj The object to locate
309 * @param[out] index The index of the last occurrence of the specified object
310 * @exception E_SUCCESS The method is successful.
311 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
314 virtual result LastIndexOf(const Object& obj, int& index) const;
317 * Inserts the object at the specified location.
321 * @return An error code
322 * @param[in] pObj The pointer to object to insert
323 * @param[in] index The index at which the object must be inserted
324 * @exception E_SUCCESS The method is successful.
325 * @exception E_INVALID_ARG The specified input parameter is invalid.
326 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
327 * the specified @c index is greater than the number of elements or less than @c 0.
328 * @remarks If the @c index equals to the number of elements, then the new element
329 * is added at the end of this list.
330 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
334 virtual result InsertAt(Object* pObj, int index);
337 * Inserts the elements of the collection at the specified location.
341 * @return An error code
342 * @param[in] collection The collection to insert elements from
343 * @param[in] startIndex The starting index at which the elements must be inserted
344 * @exception E_SUCCESS The method is successful.
345 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
346 * the specified @c startIndex is either greater than the number of elements or less than @c 0.
347 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
348 * the @c collection is modified during the operation of this method.
349 * @remarks If the @c startIndex equals to the number of elements then the new elements
350 * are added at the end of this list.
351 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
355 virtual result InsertItemsFrom(const ICollection& collection, int startIndex);
358 * Removes the first occurrence of the specified object from the list.
362 * @return An error code
363 * @param[in] obj An object to remove
364 * @exception E_SUCCESS The method is successful.
365 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
369 virtual result Remove(const Object& obj);
372 * Removes the object at the specified location in the list.
376 * @return An error code
377 * @param[in] index The index at which the object must be removed
378 * @exception E_SUCCESS The method is successful.
379 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
380 * The specified @c index is equal to or greater than the number of elements or less than @c 0.
383 virtual result RemoveAt(int index);
386 * Removes all elements within the specified range from the list.
390 * @return An error code
391 * @param[in] startIndex The starting index of the range
392 * @param[in] count The number of element to remove
393 * @exception E_SUCCESS The method is successful.
394 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
395 * - The specified index is outside the bounds of the data structure. @n
396 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
397 * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0.
399 * @see InsertItemsFrom()
401 virtual result RemoveItems(int startIndex, int count);
404 * Removes all the elements that are common in the specified @c collection
409 * @return An error code
410 * @param[in] collection The collection to remove from this list
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
413 * the @c collection is modified during the operation of this method.
417 virtual result RemoveItems(const ICollection& collection);
421 * Removes all of the object pointers in the collection and also removes all of the objects depending on the specified element deleter.
422 * This method can be called before deleting the objects in a collection.
427 virtual void RemoveAll(void);
430 * Replaces the object at the specified index with the given object.
434 * @return An error code
435 * @param[in] pObj The pointer to object to set
436 * @param[in] index The index at which the object must be set
437 * @exception E_SUCCESS The method is successful.
438 * @exception E_INVALID_ARG The specified input parameter is invalid.
439 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
440 * the specified @c index is equal to or greater than the number of elements or less than @c 0.
443 virtual result SetAt(Object* pObj, int index);
446 * Sorts the elements of this list using the comparer provided.
450 * @return An error code
451 * @param[in] comparer The IComparer implementation to use when comparing elements
452 * @exception E_SUCCESS The method is successful.
453 * @exception E_INVALID_ARG The specified input parameter is invalid, or
454 * the @c comparer is not valid.
456 virtual result Sort(const IComparer& comparer);
459 * Gets the number of objects currently stored in this list.
463 * @return The number of objects currently stored in this list
465 virtual int GetCount(void) const;
468 * Checks whether the list contains the specified object.
472 * @return @c true if the list contains the specified object, @n
474 * @param[in] obj The object to locate
477 virtual bool Contains(const Object& obj) const;
480 * Checks whether the list contains all the elements of the specified collection.
484 * @return @c true if this list contains all of the elements in the specified collection, @n
486 * @param[in] collection The collection to check for containment in this list
487 * @exception E_SUCCESS The method is successful.
488 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
489 * the @c collection is modified during the operation of this method.
490 * @remarks The specific error code can be accessed using the GetLastResult() method.
491 * @remarks If the given @c collection is empty, this method will return @c true.
494 virtual bool ContainsAll(const ICollection& collection) const;
497 * Compares the given object with the calling %LinkedList object.
501 * @return @c true if the specified instance equals the current instance, @n
503 * @param[in] obj The object to compare with the calling object
504 * @remarks This method returns @c true only if the specified object is also an instance of the %LinkedList class,
505 * both lists have the same size, and all corresponding pairs of elements in the two lists are equal.
506 * In other words, two lists are equal if they contain the same elements in the same order.
508 virtual bool Equals(const Object& obj) const;
511 * Gets the hash value of the current instance.
515 * @return The hash value of the current instance
516 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
517 * the used hash function must generate a random distribution for all inputs.
519 virtual int GetHashCode(void) const;
522 * Gets the element deleter of the collection.
526 * @return A function pointer to the existing element deleter
528 virtual DeleterFunctionType GetDeleter(void) const;
532 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
534 * @param[in] list The %LinkedList object to initialize the new object
536 LinkedList(const LinkedList& list);
539 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
541 * @param[in] list An instance of %LinkedList
543 LinkedList& operator =(const LinkedList& list);
546 * Allocates and adds a memory block.
548 * @return An error code
549 * @param[in] blockSize The size of block to allocate
550 * @exception E_SUCCESS The method is successful.
552 result AddBlock(int blockSize = DEFAULT_CAPACITY);
555 * Frees memory blocks of the list.
558 void DeleteBlock(void);
561 * Inserts an object to the beginning of the %LinkedList.
563 * @return An error code
564 * @param[in] pObj The pointer to object to insert
565 * @exception E_SUCCESS The method is successful.
567 result InsertFirst(Object* pObj);
570 * Inserts an object to the end of the %LinkedList.
572 * @return An error code
573 * @param[in] pObj The pointer to object to insert
574 * @exception E_SUCCESS The method is successful.
576 result InsertLast(Object* pObj);
579 * Inserts an object after the specified node.
581 * @return An error code
582 * @param[in] pObj The pointer to object to insert
583 * @param[in] pPrevNode The node after which the object must inserted
584 * @exception E_SUCCESS The method is successful.
586 result InsertNext(Object* pObj, _ListNode* pPrevNode);
589 * Gets a node from Available node list.
591 * @return A pointer to a new List Node if successful, @n
592 * else @c null if no node is available
594 _ListNode* GetNewNode(void);
597 * Gets the node at the specified index.
599 * @return A node at the specified index
600 * @param[in] index The index of the node to read
602 _ListNode* GetNode(int index) const;
605 * Removes the specified node.
607 * @param[in] pNode The pointer of the node to remove
609 void RemoveNode(_ListNode* pNode);
612 * Sets the element deleter of the collection.
616 * @param[in] deleter A function pointer to the element deleter to set
618 virtual void SetDeleter(DeleterFunctionType deleter);
620 _ListNode* __pListHead;
621 _ListNode* __pListTail;
622 _ListNode* __pAvailableHead;
623 _ListNode* __pAvailableTail;
624 _ListNode* __pBlocks;
628 static const int DEFAULT_CAPACITY = 10;
629 DeleterFunctionType __deleter;
631 friend class _LinkedListEnumerator;
632 friend class _LinkedListImpl;
633 class _LinkedListImpl* __pLinkedListImpl;
637 }}} // Tizen::Base::Collection
639 #endif // _FBASE_COL_LINKED_LIST_H_