Merge "[3.0] Fix Klocwork issue. 1.unused variables 2. local variable name which...
[platform/framework/native/appfw.git] / inc / FBaseColLinkedList.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                FBaseColLinkedList.h
19  * @brief               This is the header file for the %LinkedList class.
20  *
21  * This header file contains the declarations of the %LinkedList class.
22  */
23 #ifndef _FBASE_COL_LINKED_LIST_H_
24 #define _FBASE_COL_LINKED_LIST_H_
25
26 #include <FBaseColIComparer.h>
27 #include <FBaseColIList.h>
28
29 namespace Tizen { namespace Base { namespace Collection
30 {
31
32 class _ListNode;
33
34 /**
35  * @class LinkedList
36  * @brief This class represents a collection of objects that can be individually accessed by index.
37  *
38  * @since 2.0
39  *
40  * The %LinkedList class represents a collection of objects that can be individually accessed by index.
41  *
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>.
43  *
44  * The following example demonstrates how to use the %LinkedList class.
45  *
46  * @code
47  *      #include <FBase.h>
48  *
49  *      using namespace Tizen::Base;
50  *      using namespace Tizen::Base::Collection;
51  *
52  *      void
53  *      MyClass::LinkedListSample(void)
54  *      {
55  *              LinkedList list(SingleObjectDeleter);
56  *
57  *              list.Add(new Integer(1));       // 1
58  *              list.Add(new Integer(2));       // 1,2
59  *              list.Add(new Integer(3));       // 1,2,3
60  *
61  *              Integer*        pInt = static_cast< Integer* > (list.GetAt(0));
62  *
63  *              if (pValue->Equals(Integer(1))
64  *              {
65  *                      // Must be here
66  *              }
67  *
68  *              list.InsertAt(new Integer(4), 1);       // 1,4,2,3
69  *
70  *              list.Remove(Integer(3));                // 1,4,2
71  *
72  *              list.RemoveAt(0);                               // 4,2
73  *
74  *              list.Sort(IntegerComparer());   // 2,4
75  *
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)
80  *              {
81  *                      pObj = pEnum->GetCurrent();
82  *              }
83  *
84  *              delete pEnum;
85  *
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();
89  *      }
90  * @endcode
91  */
92 class _OSP_EXPORT_ LinkedList
93         : public IList
94         , public Object
95 {
96 public:
97         using IList::Add;
98         using IList::InsertAt;
99         using IList::Remove;
100         using IList::RemoveAt;
101         using IList::RemoveItems;
102         using IList::RemoveAll;
103         using IList::SetAt;
104         using IList::ContainsAll;
105         /**
106          * This is the default constructor for this class.
107          *
108          * @since 2.0
109          *
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.
114          * @see         NoOpDeleter()
115          * @see         SingleObjectDeleter()
116          * @see         ArrayDeleter()
117          */
118         explicit LinkedList(DeleterFunctionType deleter = NoOpDeleter);
119
120         /**
121          * This destructor overrides Tizen::Base::Object::~Object().
122          *
123          * @since 2.0
124          */
125         virtual ~LinkedList(void);
126
127         /**
128          * Adds the given object to the end of this list.
129          *
130          * @since 2.0
131          *
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.
137          * @see Remove()
138          */
139         virtual result Add(Object* pObj);
140
141         /**
142          * Adds the elements of the given collection to the end of this list.
143          *
144          * @since 2.0
145          *
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.
152          * @see                 RemoveItems()
153          */
154         virtual result AddItems(const ICollection& collection);
155
156         /**
157          * Gets an enumerator (an instance of the IEnumerator derived class) to the list.
158          *
159          * @since 2.0
160          *
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
165          */
166         virtual IEnumerator* GetEnumeratorN(void) const;
167
168         /**
169          * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
170          *
171          * @since 2.0
172          *
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
179          */
180         virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const;
181
182         /**
183          * Gets the object at the specified index of the calling list.
184          *
185          * @since 2.0
186          *
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.
194          * @see                 SetAt()
195          */
196         virtual const Object* GetAt(int index) const;
197
198         /**
199          * Gets the object at the specified index of the calling list.
200          *
201          * @since 2.0
202          *
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.
210          * @see                 SetAt()
211          */
212         virtual Object* GetAt(int index);
213
214         /**
215          * Gets the reference of the object at the specified index of the calling list.
216          *
217          * @since               3.0
218          *
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.
225          */
226         virtual Object*& GetAtRef(int index);
227
228         /**
229          * Gets an IList with the specified range from the calling list object.
230          *
231          * @since 2.0
232          *
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.
244          */
245         virtual IList* GetItemsN(int startIndex, int count) const;
246
247         /**
248          * Searches for an object in this list. @n
249          * Gets the index of the object if found.
250          *
251          * @since 2.0
252          *
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.
258          */
259         virtual result IndexOf(const Object& obj, int& index) const;
260
261         /**
262          * Searches for an object starting from the specified index. @n
263          * Gets the index of the object if found.
264          *
265          * @since 2.0
266          *
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.
276          * @see                 LastIndexOf()
277          */
278         virtual result IndexOf(const Object& obj, int startIndex, int& index) const;
279
280         /**
281          * Searches for an object within the specified range. @n
282          * Gets the index of the object if found.
283          *
284          * @since 2.0
285          *
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.
297          * @see                 LastIndexOf()
298          */
299         virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const;
300
301         /**
302          * Searches for the last occurrence of an object in this list. @n
303          * Gets the index of the object if found.
304          *
305          * @since 2.0
306          *
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.
312          * @see                 IndexOf()
313          */
314         virtual result LastIndexOf(const Object& obj, int& index) const;
315
316         /**
317          * Inserts the object at the specified location.
318          *
319          * @since 2.0
320          *
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.
331          * @see         Add()
332          * @see         RemoveAt()
333          */
334         virtual result InsertAt(Object* pObj, int index);
335
336         /**
337          * Inserts the elements of the collection at the specified location.
338          *
339          * @since 2.0
340          *
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.
352          * @see                 RemoveItems()
353          * @see                 AddItems()
354          */
355         virtual result InsertItemsFrom(const ICollection& collection, int startIndex);
356
357         /**
358          * Removes the first occurrence of the specified object from the list.
359          *
360          * @since 2.0
361          *
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.
366          * @see                 Add()
367          * @see                 RemoveAt()
368          */
369         virtual result Remove(const Object& obj);
370
371         /**
372          * Removes the object at the specified location in the list.
373          *
374          * @since 2.0
375          *
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.
381          * @see         InsertAt()
382          */
383         virtual result RemoveAt(int index);
384
385         /**
386          * Removes all elements within the specified range from the list.
387          *
388          * @since 2.0
389          *
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.
398          * @see                 AddItems()
399          * @see                 InsertItemsFrom()
400          */
401         virtual result RemoveItems(int startIndex, int count);
402
403         /**
404          * Removes all the elements that are common in the specified @c collection
405          * and the list.
406          *
407          * @since 2.0
408          *
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.
414          * @see                 Remove()
415          * @see                 RemoveAt()
416          */
417         virtual result RemoveItems(const ICollection& collection);
418
419
420         /**
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.
423          *
424          * @since 2.0
425          *
426          */
427         virtual void RemoveAll(void);
428
429         /**
430          * Replaces the object at the specified index with the given object.
431          *
432          * @since 2.0
433          *
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.
441          * @see                 GetAt()
442          */
443         virtual result SetAt(Object* pObj, int index);
444
445         /**
446          * Sorts the elements of this list using the comparer provided.
447          *
448          * @since 2.0
449          *
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.
455          */
456         virtual result Sort(const IComparer& comparer);
457
458         /**
459          * Gets the number of objects currently stored in this list.
460          *
461          * @since 2.0
462          *
463          * @return              The number of objects currently stored in this list
464          */
465         virtual int GetCount(void) const;
466
467         /**
468          * Checks whether the list contains the specified object.
469          *
470          * @since 2.0
471          *
472          * @return              @c true if the list contains the specified object, @n
473          *                              else @c false
474          * @param[in]   obj     The object to locate
475          * @see                 ContainsAll()
476          */
477         virtual bool Contains(const Object& obj) const;
478
479         /**
480          * Checks whether the list contains all the elements of the specified collection.
481          *
482          * @since 2.0
483          *
484          * @return              @c true if this list contains all of the elements in the specified collection, @n
485          *                              else @c false
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.
492          * @see                 Contains()
493          */
494         virtual bool ContainsAll(const ICollection& collection) const;
495
496         /**
497          * Compares the given object with the calling %LinkedList object.
498          *
499          * @since 2.0
500          *
501          * @return              @c true if the specified instance equals the current instance, @n
502          *                              else @c false
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.
507          */
508         virtual bool Equals(const Object& obj) const;
509
510         /**
511          * Gets the hash value of the current instance.
512          *
513          * @since 2.0
514          *
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.
518          */
519         virtual int GetHashCode(void) const;
520
521         /**
522          * Gets the element deleter of the collection.
523          *
524          * @since 2.0
525          *
526          * @return      A function pointer to the existing element deleter
527          */
528         virtual DeleterFunctionType GetDeleter(void) const;
529
530 private:
531         /**
532          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
533          *
534          * @param[in]   list The %LinkedList object to initialize the new object
535          */
536         LinkedList(const LinkedList& list);
537
538         /**
539          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
540          *
541          * @param[in]   list An instance of %LinkedList
542          */
543         LinkedList& operator =(const LinkedList& list);
544
545         /**
546          * Allocates and adds a memory block.
547          *
548          * @return              An error code
549          * @param[in]   blockSize               The size of block to allocate
550          * @exception   E_SUCCESS               The method is successful.
551          */
552         result AddBlock(int blockSize = DEFAULT_CAPACITY);
553
554         /**
555          * Frees memory blocks of the list.
556          *
557          */
558         void DeleteBlock(void);
559
560         /**
561          * Inserts an object to the beginning of the %LinkedList.
562          *
563          * @return              An error code
564          * @param[in]   pObj                    The pointer to object to insert
565          * @exception   E_SUCCESS               The method is successful.
566          */
567         result InsertFirst(Object* pObj);
568
569         /**
570          * Inserts an object to the end of the %LinkedList.
571          *
572          * @return              An error code
573          * @param[in]   pObj                    The pointer to object to insert
574          * @exception   E_SUCCESS               The method is successful.
575          */
576         result InsertLast(Object* pObj);
577
578         /**
579          * Inserts an object after the specified node.
580          *
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.
585          */
586         result InsertNext(Object* pObj, _ListNode* pPrevNode);
587
588         /**
589          * Gets a node from Available node list.
590          *
591          * @return              A pointer to a new List Node if successful, @n
592          *                              else @c null if no node is available
593          */
594         _ListNode* GetNewNode(void);
595
596         /**
597          * Gets the node at the specified index.
598          *
599          * @return              A node at the specified index
600          * @param[in]   index The index of the node to read
601          */
602         _ListNode* GetNode(int index) const;
603
604         /**
605          * Removes the specified node.
606          *
607          * @param[in]   pNode The pointer of the node to remove
608          */
609         void RemoveNode(_ListNode* pNode);
610
611         /**
612          * Sets the element deleter of the collection.
613          *
614          * @since 2.0
615          *
616          * @param[in]   deleter A function pointer to the element deleter to set
617          */
618         virtual void SetDeleter(DeleterFunctionType deleter);
619
620         _ListNode* __pListHead;
621         _ListNode* __pListTail;
622         _ListNode* __pAvailableHead;
623         _ListNode* __pAvailableTail;
624         _ListNode* __pBlocks;
625         int __count;
626         int __capacity;
627         int __modCount;
628         static const int DEFAULT_CAPACITY = 10;
629         DeleterFunctionType __deleter;
630
631         friend class _LinkedListEnumerator;
632         friend class _LinkedListImpl;
633         class _LinkedListImpl* __pLinkedListImpl;
634
635 }; // LinkedList
636
637 }}} // Tizen::Base::Collection
638
639 #endif // _FBASE_COL_LINKED_LIST_H_