Flush app registry before releasing file lock
[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 an index.
37  *
38  * @since 2.0
39  *
40  * The %LinkedList class represents a collection of objects that can be individually accessed by an 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         A function pointer to the type of the element deleter
111          * @remarks     To create an owing collection, set the element deleter value as @c SingleObjectDeleter. @n
112          *                              This gives the collection the ownership of the elements and the collection destroys the elements. @n
113          *                              On the other hand, to create a non-owning collection, do not set the element deleter value, as @c NoOpDeleter is the default element deleter. @n
114          *                              It means that you do not transfer the ownership of the elements to the collection.
115          * @see         NoOpDeleter()
116          * @see         SingleObjectDeleter()
117          * @see         ArrayDeleter()
118          */
119         explicit LinkedList(DeleterFunctionType deleter = NoOpDeleter);
120
121         /**
122          * This destructor overrides Tizen::Base::Object::~Object().
123          *
124          * @since 2.0
125          */
126         virtual ~LinkedList(void);
127
128         /**
129          * Adds the given object to the end of this list.
130          *
131          * @since 2.0
132          *
133          * @return              An error code
134          * @param[in]   pObj                    A pointer to the object to add
135          * @exception   E_SUCCESS               The method is successful.
136          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
137          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
138          * @see Remove()
139          */
140         virtual result Add(Object* pObj);
141
142         /**
143          * Adds the elements of the given collection to the end of this list.
144          *
145          * @since 2.0
146          *
147          * @return              An error code
148          * @param[in]   collection                      The collection to add
149          * @exception   E_SUCCESS                       The method is successful.
150          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
151          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
152          *                                                                      - The specified @c collection is modified during the operation of this method.
153          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
154          * @see                 RemoveItems()
155          */
156         virtual result AddItems(const ICollection& collection);
157
158         /**
159          * Gets the enumerator (an instance of the IEnumerator derived class) of the list.
160          *
161          * @since 2.0
162          *
163          * @return              The enumerator of the calling list object, @n
164          *                              else @c null if an exception occurs
165          * @remarks             The specific error code can be accessed using the GetLastResult() method.
166          */
167         virtual IEnumerator* GetEnumeratorN(void) const;
168
169         /**
170          * Gets the bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of the list.
171          *
172          * @since 2.0
173          *
174          * @return                      An instance of the IBidirectionalEnumerator derived class, @n
175          *                                      else @c null if an exception occurs
176          * @remarks
177          *                                      - Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
178          *                                      to iterate over a collection (an instance of the IList derived class).
179          *                                      - The specific error code can be accessed using GetLastResult() method.
180          */
181         virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const;
182
183         /**
184          * Gets the object at the specified @c index of the calling list.
185          *
186          * @since 2.0
187          *
188          * @return              A pointer to the object at the specified index of the list, @n
189          *                              else @c null if the index is invalid
190          * @param[in]   index                                   The index of the object to read
191          * @exception   E_SUCCESS                               The method is successful.
192          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
193          *                                                                              - The specified @c index is outside the bounds of the data structure.
194          *                                                                              - The specified @c index is either greater than or equal to the number of elements.
195          *                                                                              - The specified @c index is less than @c 0.
196          * @remarks             The specific error code can be accessed using the GetLastResult() method.
197          * @see                 SetAt()
198          */
199         virtual const Object* GetAt(int index) const;
200
201         /**
202          * Gets the object at the specified @c index of the calling list.
203          *
204          * @since 2.0
205          *
206          * @return              A pointer to the object at the specified index of the list, @n
207          *                              else @c null if the index is invalid
208          * @param[in]   index                                   The index of the object to read
209          * @exception   E_SUCCESS                               The method is successful.
210          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
211          *                                                                              - The specified @c index is outside the bounds of the data structure.
212          *                                                                              - The specified @c index is either greater than or equal to the number of elements.
213          *                                                                              - The specified @c index is less than @c 0.
214          * @remarks             The specific error code can be accessed using the GetLastResult() method.
215          * @see                 SetAt()
216          */
217         virtual Object* GetAt(int index);
218
219         /**
220          * Gets the IList with the specified range from the calling list object.
221          *
222          * @since 2.0
223          *
224          * @return              An IList pointer , @n
225          *                              else @c null if an exception occurs
226          * @param[in]   startIndex                              The starting index of the range
227          * @param[in]   count                                   The number of elements to read
228          * @exception   E_SUCCESS                               The method is successful.
229          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
230          *                                                                              - The specified @c index is outside the bounds of the data structure.
231          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements.
232          *                                                                              - The specified @c startIndex is less than @c 0.
233          *                                                                              - The specified @c count is either greater than the number of elements starting from @c startIndex.
234          *                                                                              - The specified @c count is less than @c 0.
235          * @remarks
236          *                              - The IList stores just the pointers to the elements in the list and not the elements themselves.
237          *                              - The specific error code can be accessed using the GetLastResult() method.
238          */
239         virtual IList* GetItemsN(int startIndex, int count) const;
240
241         /**
242          * Searches for an object in this list. @n
243          * Gets the @c index of the object if found.
244          *
245          * @since 2.0
246          *
247          * @return              An error code
248          * @param[in]   obj                                     The object to locate
249          * @param[out]  index                           The index of the object
250          * @exception   E_SUCCESS                       The method is successful.
251          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
252          */
253         virtual result IndexOf(const Object& obj, int& index) const;
254
255         /**
256          * Searches for an object starting from the specified @c startIndex. @n
257          * Gets the @c index of the object if found.
258          *
259          * @since 2.0
260          *
261          * @return              An error code
262          * @param[in]   obj                                     The object to locate
263          * @param[in]   startIndex                              The starting index for the search @n
264          *                                                                              It must be less than the number of elements.
265          * @param[out]  index                                   The index of the object
266          * @exception   E_SUCCESS                               The method is successful.
267          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
268          *                                                                              - The specified @c index is outside the bounds of the data structure.
269          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
270          *                                                                              - The specified @c startIndex is less than @c 0.
271          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
272          * @see                 LastIndexOf()
273          */
274         virtual result IndexOf(const Object& obj, int startIndex, int& index) const;
275
276         /**
277          * Searches for an object within the specified range. @n
278          * Gets the @c index of the object if found.
279          *
280          * @since 2.0
281          *
282          * @return              An error code
283          * @param[in]   obj                                     The object to locate
284          * @param[in]   startIndex                              The starting index of the range
285          * @param[in]   count                                   The number of elements to read
286          * @param[out]  index                                   The index of the object
287          * @exception   E_SUCCESS                               The method is successful.
288          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
289          *                                                                              - The specified @c index is outside the bounds of the data structure.
290          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
291          *                                                                              - The specified @c startIndex is less than @c 0.
292          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
293          *                                                                              - The specified @c count is less than @c 0.
294          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
295          * @see                 LastIndexOf()
296          */
297         virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const;
298
299         /**
300          * Searches for the last occurrence of an object in this list. @n
301          * Gets the @c index of the object if found.
302          *
303          * @since 2.0
304          *
305          * @return              An error code
306          * @param[in]   obj                             The object to locate
307          * @param[out]  index                           The index of the last occurrence of the specified object
308          * @exception   E_SUCCESS                       The method is successful.
309          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
310          * @see                 IndexOf()
311          */
312         virtual result LastIndexOf(const Object& obj, int& index) const;
313
314         /**
315          * Inserts the object at the specified location.
316          *
317          * @since 2.0
318          *
319          * @return              An error code
320          * @param[in]   pObj                                    A pointer to the object to insert
321          * @param[in]   index                                   The index at which the object is inserted
322          * @exception   E_SUCCESS                               The method is successful.
323          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
324          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
325          *                                                                              - The specified @c index is outside the bounds of the data structure.
326          *                                                                              - The specified @c index is greater than the number of elements.
327          *                                                                              - The specified @c index is less than @c 0.
328          * @remarks
329          *                              - If the @c index is equal to the number of elements, then the new elements
330          *                              is added at the end of this list.
331          *                              - This method performs a shallow copy. It inserts just the pointer and not the element itself.
332          * @see         Add()
333          * @see         RemoveAt()
334          */
335         virtual result InsertAt(Object* pObj, int index);
336
337         /**
338          * Inserts the elements of the collection at the specified location.
339          *
340          * @since 2.0
341          *
342          * @return              An error code
343          * @param[in]   collection                              The collection to insert elements from
344          * @param[in]   startIndex                              The starting index at which the elements are inserted
345          * @exception   E_SUCCESS                               The method is successful.
346          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
347          *                                                                              - The specified index is outside the bounds of the data structure.
348          *                                                                              - The specified @c startIndex is greater than the number of elements.
349          *                                                                              - The specified @c startIndex is less than @c 0.
350          * @exception   E_INVALID_OPERATION             Either of the following conditions has occurred:
351          *                                                                              - The current state of the instance prohibits the execution of the specified operation.
352          *                                                                              - The specified @c collection is modified during the operation of this method.
353          * @remarks
354          *                              - If the specified @c startIndex is equal to the number of elements, then the new elements
355          *                                are added at the end of this list.
356          *                              - This method performs a shallow copy. It inserts just the pointer and not the element itself.
357          * @see                 RemoveItems()
358          * @see                 AddItems()
359          */
360         virtual result InsertItemsFrom(const ICollection& collection, int startIndex);
361
362         /**
363          * Removes the first occurrence of the specified object from the list.
364          *
365          * @since 2.0
366          *
367          * @return              An error code
368          * @param[in]   obj                             The object to remove
369          * @exception   E_SUCCESS               The method is successful.
370          * @exception   E_OBJ_NOT_FOUND The specified @c obj has not been found.
371          * @see                 Add()
372          * @see                 RemoveAt()
373          */
374         virtual result Remove(const Object& obj);
375
376         /**
377          * Removes the object at the specified location in the list.
378          *
379          * @since 2.0
380          *
381          * @return              An error code
382          * @param[in]   index                           The index at which the object is removed
383          * @exception   E_SUCCESS                       The method is successful.
384          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
385          *                                                                      - The specified @c index is outside the bounds of the data structure.
386          *                                                                      - The specified @c index is either greater than or equal to the number of elements.
387          *                                                                      - The specified @c index is less than @c 0.
388          * @see         InsertAt()
389          */
390         virtual result RemoveAt(int index);
391
392         /**
393          * Removes all the elements within the specified range from the list.
394          *
395          * @since 2.0
396          *
397          * @return              An error code
398          * @param[in]   startIndex                      The starting index of the range
399          * @param[in]   count                           The number of elements to remove
400          * @exception   E_SUCCESS                       The method is successful.
401          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
402          *                                                                      - The specified @c index is outside the bounds of the data structure.
403          *                                                                      - The specified @c startIndex is either greater than or equal to the number of elements.
404          *                                                                      - The specified @c startIndex is less than @c 0.
405          *                                                                      - The specified @c count is greater than the number of elements starting from @c startIndex.
406          *                                                                      - The specified @c count is less than @c 0.
407          * @see                 AddItems()
408          * @see                 InsertItemsFrom()
409          */
410         virtual result RemoveItems(int startIndex, int count);
411
412         /**
413          * Removes all the elements that are common in the specified @c collection
414          * and the list.
415          *
416          * @since 2.0
417          *
418          * @return              An error code
419          * @param[in]   collection                      The collection to remove from this list
420          * @exception   E_SUCCESS                       The method is successful.
421          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
422          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
423          *                                                                      - The specified @c collection is modified during the operation of this method.
424          * @see                 Remove()
425          * @see                 RemoveAt()
426          */
427         virtual result RemoveItems(const ICollection& collection);
428
429
430         /**
431          * Removes all of the object pointers in the collection and also removes all the objects depending on the specified element deleter.
432          * This method can be called before deleting the objects in a collection.
433          *
434          * @since 2.0
435          *
436          */
437         virtual void RemoveAll(void);
438
439         /**
440          * Replaces the object at the specified @c index with the given object.
441          *
442          * @since 2.0
443          *
444          * @return              An error code
445          * @param[in]   pObj                            A pointer to the object to set
446          * @param[in]   index                           The index at which the object is set
447          * @exception   E_SUCCESS                       The method is successful.
448          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
449          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
450          *                                                                      - The specified @c index is outside the bounds of the data structure.
451          *                                                                      - The specified @c index is either greater than or equal to the number of elements.
452          *                                                                      - The specified @c index is less than @c 0.
453          * @see                 GetAt()
454          */
455         virtual result SetAt(Object* pObj, int index);
456
457         /**
458          * Sorts the elements of this list using the @c comparer provided.
459          *
460          * @since 2.0
461          *
462          * @return              An error code
463          * @param[in]   comparer                The IComparer implementation to use when comparing the elements
464          * @exception   E_SUCCESS               The method is successful.
465          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
466          *                                                              - The specified input parameter is invalid.
467          *                                                              - The specified @c comparer is invalid.
468          */
469         virtual result Sort(const IComparer& comparer);
470
471         /**
472          * Gets the number of objects currently stored in this list.
473          *
474          * @since 2.0
475          *
476          * @return              The number of objects currently stored in this list
477          */
478         virtual int GetCount(void) const;
479
480         /**
481          * Checks whether the list contains the specified object.
482          *
483          * @since 2.0
484          *
485          * @return              @c true if the list contains the specified object, @n
486          *                              else @c false
487          * @param[in]   obj     The object to locate
488          * @see                 ContainsAll()
489          */
490         virtual bool Contains(const Object& obj) const;
491
492         /**
493          * Checks whether the list contains all the elements of the specified @c collection.
494          *
495          * @since 2.0
496          *
497          * @return              @c true if this list contains all the elements in the specified collection, @n
498          *                              else @c false
499          * @param[in]   collection                      The collection to check for containment in this list
500          * @exception   E_SUCCESS                       The method is successful.
501          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
502          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
503          *                                                                      - The @c collection is modified during the operation of this method.
504          * @remarks
505          *                              - The specific error code can be accessed using the GetLastResult() method.
506          *                              - If the given @c collection is empty, this method returns @c true.
507          * @see                 Contains()
508          */
509         virtual bool ContainsAll(const ICollection& collection) const;
510
511         /**
512          * Compares the given object with the calling %LinkedList object.
513          *
514          * @since 2.0
515          *
516          * @return              @c true if the specified instance equals the current instance, @n
517          *                              else @c false
518          * @param[in]   obj The object to compare with the calling object
519          * @remarks
520          *                              - This method returns @c true only if the specified object is also an instance of the %LinkedList class,
521          *                              both lists have the same size, and all corresponding pairs of elements in the two lists are equal.
522          *                              - In other words, two lists are equal if they contain the same elements in the same order.
523          */
524         virtual bool Equals(const Object& obj) const;
525
526         /**
527          * Gets the hash value of the current instance.
528          *
529          * @since 2.0
530          *
531          * @return      The hash value of the current instance
532          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. @n
533          *                      For better performance, the used hash function must generate a random distribution for all the inputs.
534          */
535         virtual int GetHashCode(void) const;
536
537         /**
538          * Gets the element deleter of the collection.
539          *
540          * @since 2.0
541          *
542          * @return      A function pointer to the existing element deleter
543          */
544         virtual DeleterFunctionType GetDeleter(void) const;
545
546 private:
547         /**
548          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
549          *
550          * @param[in]   list The %LinkedList object to initialize the new object
551          */
552         LinkedList(const LinkedList& list);
553
554         /**
555          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
556          *
557          * @param[in]   list An instance of %LinkedList
558          */
559         LinkedList& operator =(const LinkedList& list);
560
561         /**
562          * Allocates and adds a memory block.
563          *
564          * @return              An error code
565          * @param[in]   blockSize               The size of block to allocate
566          * @exception   E_SUCCESS               The method is successful.
567          */
568         result AddBlock(int blockSize = DEFAULT_CAPACITY);
569
570         /**
571          * Frees memory blocks of the list.
572          *
573          */
574         void DeleteBlock(void);
575
576         /**
577          * Inserts an object to the beginning of the %LinkedList.
578          *
579          * @return              An error code
580          * @param[in]   pObj                    The pointer to object to insert
581          * @exception   E_SUCCESS               The method is successful.
582          */
583         result InsertFirst(Object* pObj);
584
585         /**
586          * Inserts an object to the end of the %LinkedList.
587          *
588          * @return              An error code
589          * @param[in]   pObj                    The pointer to object to insert
590          * @exception   E_SUCCESS               The method is successful.
591          */
592         result InsertLast(Object* pObj);
593
594         /**
595          * Inserts an object after the specified node.
596          *
597          * @return              An error code
598          * @param[in]   pObj                    The pointer to object to insert
599          * @param[in]   pPrevNode               The node after which the object must inserted
600          * @exception   E_SUCCESS               The method is successful.
601          */
602         result InsertNext(Object* pObj, _ListNode* pPrevNode);
603
604         /**
605          * Gets a node from Available node list.
606          *
607          * @return              A pointer to a new List Node, @n
608          *                              else @c null if no node is available
609          */
610         _ListNode* GetNewNode(void);
611
612         /**
613          * Gets the node at the specified index.
614          *
615          * @return              A node at the specified index
616          * @param[in]   index The index of the node to read
617          */
618         _ListNode* GetNode(int index) const;
619
620         /**
621          * Removes the specified node.
622          *
623          * @param[in]   pNode The pointer of the node to remove
624          */
625         void RemoveNode(_ListNode* pNode);
626
627         /**
628          * Sets the element deleter of the collection.
629          *
630          * @since 2.0
631          *
632          * @param[in]   deleter A function pointer to the element deleter to set
633          */
634         virtual void SetDeleter(DeleterFunctionType deleter);
635
636         _ListNode* __pListHead;
637         _ListNode* __pListTail;
638         _ListNode* __pAvailableHead;
639         _ListNode* __pAvailableTail;
640         _ListNode* __pBlocks;
641         int __count;
642         int __capacity;
643         int __modCount;
644         static const int DEFAULT_CAPACITY = 10;
645         DeleterFunctionType __deleter;
646
647         friend class _LinkedListEnumerator;
648         friend class _LinkedListImpl;
649         class _LinkedListImpl* __pLinkedListImpl;
650
651 }; // LinkedList
652
653 }}} // Tizen::Base::Collection
654
655 #endif // _FBASE_COL_LINKED_LIST_H_