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 FBaseColArrayList.h
19 * @brief This is the header file for the %ArrayList class.
21 * This header file contains the declarations of the %ArrayList class.
23 #ifndef _FBASE_COL_ARRAY_LIST_H_
24 #define _FBASE_COL_ARRAY_LIST_H_
26 #include <FBaseObject.h>
27 #include <FBaseColIComparer.h>
28 #include <FBaseColIList.h>
31 namespace Tizen { namespace Base { namespace Collection
36 * @brief This class represents a collection of objects that can be individually accessed by an index.
41 * The %ArrayList class represents a collection of objects that can be individually accessed by an index.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/arraylist_linkedlist.htm">ArrayList and LinkedList</a>.
45 * The following example demonstrates how to use the %ArrayList class.
51 * using namespace Tizen::Base;
52 * using namespace Tizen::Base::Collection;
56 * MyClass::ArrayListSample(void)
58 * ArrayList list(SingleObjectDeleter);
62 * list.Add(new Integer(1)); // 1
63 * list.Add(new Integer(2)); // 1,2
64 * list.Add(new Integer(3)); // 1,2,3
66 * Integer* pInt = static_cast< Integer* > (list.GetAt(0));
68 * if (pInt->Equals(Integer(1)))
73 * list.InsertAt(new Integer(4), 1); // 1,4,2,3
75 * list.Remove(Integer(3)); // 1,4,2
77 * list.RemoveAt(0); // 4,2
79 * list.Sort(IntegerComparer()); // 2,4
81 * // Uses an enumerator to access elements in the list
82 * IEnumerator* pEnum = list.GetEnumeratorN();
83 * Object* pObj = null;
84 * while (pEnum->MoveNext() == E_SUCCESS)
86 * pObj = pEnum->GetCurrent();
92 * // Deallocates all objects
93 * // Because the destructor calls RemoveAll() internally, you do not need to call RemoveAll() to destroy all elements at the end.
94 * // list.RemoveAll();
98 class _OSP_EXPORT_ ArrayList
104 using IList::InsertAt;
106 using IList::RemoveAt;
107 using IList::RemoveItems;
108 using IList::RemoveAll;
110 using IList::ContainsAll;
112 * This is the default constructor for this class.
116 * @param[in] deleter The function pointer to type of the element deleter
117 * @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
118 * 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.
119 * It means that you do not transfer the ownership of elements to the collection.
120 * @remarks After creating an instance of the %ArrayList class, one of the Construct() methods must be called explicitly to initialize this instance.
122 * @see SingleObjectDeleter()
123 * @see ArrayDeleter()
125 explicit ArrayList(DeleterFunctionType deleter = NoOpDeleter);
128 * This destructor overrides Tizen::Base::Object::~Object().
132 virtual ~ArrayList(void);
135 * Initializes this instance of %ArrayList with the specified parameter and sets its initial capacity to the
140 * @return An error code
141 * @param[in] capacity The number of elements @n
142 * The default capacity is @c 10.
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_INVALID_ARG A specified input parameter is invalid, or
145 * the specified @c capacity is negative.
146 * @remarks If the number of elements added to the list reaches the current capacity,
147 * the capacity is automatically increased by memory reallocation.
148 * Therefore, if the size of the list can be estimated,
149 * specifying the initial capacity eliminates the need to perform a number of
150 * resizing operations while adding elements to the list.
153 result Construct(int capacity = DEFAULT_CAPACITY);
157 * Initializes this instance of %ArrayList by copying the elements of the specified
159 * The capacity of the list is the same as the number of elements copied.
163 * @return An error code
164 * @param[in] collection A collection to add
165 * @exception E_SUCCESS The method is successful.
166 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
167 * the @c collection is modified during the operation of this method.
168 * @remarks This method performs a shallow copy. It copies just the pointer; not the element itself.
171 result Construct(const ICollection& collection);
174 * Adds the specified object to the end of this list.
178 * @return An error code
179 * @param[in] pObj An pointer to object to add
180 * @exception E_SUCCESS The method is successful.
181 * @exception E_INVALID_ARG The specified input parameter is invalid.
182 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
185 virtual result Add(Object* pObj);
189 * Adds the elements of the specified @c collection to the end of this list.
193 * @return An error code
194 * @param[in] collection A collection to add
195 * @exception E_SUCCESS The method is successful.
196 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
197 * the @c collection is modified during the operation of this method.
198 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
201 virtual result AddItems(const ICollection& collection);
205 * Gets an enumerator (an instance of the IEnumerator-derived class) of this list.
209 * @return An instance of the IEnumerator-derived class, @n
210 * else @c null if some exception occurs
211 * @remarks The specific error code can be accessed using the GetLastResult() method.
213 virtual IEnumerator* GetEnumeratorN(void) const;
216 * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
220 * @return An instance of the IBidirectionalEnumerator derived class, @n
221 * else @c null if some exception occurs
222 * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
223 * to iterate over a collection (an instance of the IList derived class).
224 * The specific error code can be accessed using GetLastResult() method.
225 * @see Tizen::Base::Collection::IBidirectionalEnumerator
227 virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const;
230 * Gets the object at the specified @c index of this list.
234 * @return The object at the specified @c index of this list, @n
235 * else @c null if the index is not valid
236 * @param[in] index The index of the object in the calling list to read
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure, or
239 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
240 * @remarks The specific error code can be accessed using the GetLastResult() method.
243 virtual const Object* GetAt(int index) const;
247 * Gets the object at the specified @c index of this list.
251 * @return The object at the specified @c index of this list, @n
252 * else @c null if the index is not valid
253 * @param[in] index The index of the object to read
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure, or
256 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
257 * @remarks The specific error code can be accessed using the GetLastResult() method.
260 virtual Object* GetAt(int index);
263 * Gets the IList within the specified range of this list.
267 * @return A pointer to IList, @n
268 * else @c null if some exception occurs
269 * @param[in] startIndex The starting index of the range
270 * @param[in] count The number of elements to read
271 * @exception E_SUCCESS The method is successful.
272 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
273 * - The specified index is outside the bounds of the data structure. @n
274 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
275 * - The @c count is greater than the number of elements starting from @c startIndex
277 * @remarks The IList stores just the pointers to the elements in the list, not the elements themselves.
278 * The specific error code can be accessed using the GetLastResult() method.
280 virtual IList* GetItemsN(int startIndex, int count) const;
283 * Searches for an object in this list. @n
284 * Gets the index of the object if found.
288 * @return An error code
289 * @param[in] obj The object to locate
290 * @param[out] index The index of the object
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
295 virtual result IndexOf(const Object& obj, int& index) const;
298 * Searches for an object starting from the specified index. @n
299 * Gets the index of the object if found.
303 * @return An error code
304 * @param[in] obj The object to locate
305 * @param[in] startIndex The starting index for the search @n
306 * It must be less than the number of elements.
307 * @param[out] index The index of the object
308 * @exception E_SUCCESS The method is successful.
309 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
310 * the specified @c startIndex is either equal to or greater than the number of elements or less than @c 0.
311 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
314 virtual result IndexOf(const Object& obj, int startIndex, int& index) const;
317 * Searches for an object within the specified range. @n
318 * Gets the index of the object if found.
322 * @return An error code
323 * @param[in] obj The object to locate
324 * @param[in] startIndex The starting index of the range
325 * @param[in] count The number of elements to read
326 * @param[out] index The index of the object
327 * @exception E_SUCCESS The method is successful.
328 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
329 * - The specified index is outside the bounds of the data structure. @n
330 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
331 * - The @c count is greater than the number of elements starting from @c startIndex
333 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
336 virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const;
339 * Searches for the last occurrence of an object in this list. @n
340 * Gets the index of the object if found.
344 * @return An error code
345 * @param[in] obj The object to locate
346 * @param[out] index The index of the last occurrence of the specified object
347 * @exception E_SUCCESS The method is successful.
348 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
351 virtual result LastIndexOf(const Object& obj, int& index) const;
354 * Inserts the object at the specified location.
358 * @return An error code
359 * @param[in] pObj The pointer to object to insert
360 * @param[in] index The index at which the object must be inserted
361 * @exception E_SUCCESS The method is successful.
362 * @exception E_INVALID_ARG The specified input parameter is invalid.
363 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
364 * the @c index is greater than the number of elements or less than @c 0.
365 * @remarks The elements that follow the insertion point move down to accommodate the new element.
366 * If the @c index equals to the number of elements, then the new element
367 * is added at the end of this list.
368 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
372 virtual result InsertAt(Object* pObj, int index);
375 * Inserts the elements of the collection at the specified location.
379 * @return An error code
380 * @param[in] collection The collection to insert
381 * @param[in] startIndex The starting index at which the collection must be inserted
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
384 * the @c startIndex is greater than the number of elements or less than @c 0.
385 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
386 * the @c collection is modified during the operation of this method.
387 * @remarks The elements that follow the insertion point move down to accommodate the new element.
388 * If the @c startIndex equals to the number of elements then the new elements
389 * are added at the end of this list.
390 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
394 virtual result InsertItemsFrom(const ICollection& collection, int startIndex);
397 * Removes the first occurrence of the specified object.
401 * @return An error code
402 * @param[in] obj An object to remove
403 * @exception E_SUCCESS The method is successful.
404 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
409 virtual result Remove(const Object& obj);
412 * Removes the object at the specified location.
416 * @return An error code
417 * @param[in] index The index at which the object must be removed
418 * @exception E_SUCCESS The method is successful.
419 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
420 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
421 * @remarks The elements that follow the deletion point move up to occupy the vacated spot.
425 virtual result RemoveAt(int index);
428 * Removes all the elements within the specified range.
432 * @return An error code
433 * @param[in] startIndex The starting index of the range
434 * @param[in] count The number of elements to read
435 * @exception E_SUCCESS The method is successful.
436 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
437 * - The specified index is outside the bounds of the data structure. @n
438 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
439 * - The @c count is greater than the number of elements starting from @c startIndex
441 * @remarks The elements that follow the deletion point move up to occupy the vacated spot.
444 virtual result RemoveItems(int startIndex, int count);
447 * Removes all of the elements that are in the intersection of the specified @c collection
452 * @return An error code
453 * @param[in] collection The collection to remove from this list
454 * @exception E_SUCCESS The method is successful.
455 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
456 * the @c collection is modified during the operation of this method.
460 virtual result RemoveItems(const ICollection& collection);
463 * Removes all of the object pointers in the collection and also removes all of the objects depending on the specified element deleter.
464 * The %RemoveAll() can be called before the collection is deleted.
468 virtual void RemoveAll(void);
471 * Replaces the object at the specified @c index with the specified object.
475 * @return An error code
476 * @param[in] pObj An pointer to object to set
477 * @param[in] index The index at which the object must be set
478 * @exception E_SUCCESS The method is successful.
479 * @exception E_INVALID_ARG The specified input parameter is invalid.
480 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
481 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
484 virtual result SetAt(Object* pObj, int index);
487 * Sets the capacity of this list to the specified value.
491 * @return An error code
492 * @param[in] newCapacity The new capacity of this list
493 * @exception E_SUCCESS The method is successful.
494 * @exception E_INVALID_ARG The specified input parameter is invalid, or
495 * the @c newCapacity is negative.
496 * @remarks When the new capacity is less than the current capacity, the elements
497 * within the truncated memory are not destroyed.
502 virtual result SetCapacity(int newCapacity);
505 * Sorts the elements of this list using the comparer provided.
509 * @return An error code
510 * @param[in] comparer The IComparer implementation to use when comparing elements
511 * @exception E_SUCCESS The method is successful.
512 * @exception E_INVALID_ARG The specified input parameter is invalid.
514 virtual result Sort(const IComparer& comparer);
517 * Sets the capacity to the actual number of elements in this list.
521 virtual void Trim(void);
524 * Gets the current capacity of this list.
528 * @return The current capacity of this list
531 virtual int GetCapacity(void) const;
534 * Gets the number of objects currently stored in this list.
538 * @return The number of objects currently stored in this list
540 virtual int GetCount(void) const;
543 * Checks whether a list contains the specified object.
547 * @return @c true if the object is present in the list, @n
549 * @param[in] obj The object to locate
552 virtual bool Contains(const Object& obj) const;
555 * Checks whether the list contains all the elements of the specified @c collection.
559 * @return @c true if the list contains all the elements of the specified @c collection, @n
561 * @param[in] collection The collection to check for in the list
562 * @exception E_SUCCESS The method is successful.
563 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
564 * the @c collection is modified during the operation of this method.
565 * @remarks The specific error code can be accessed using the GetLastResult() method.
566 * @remarks If the given @c collection is empty, this method will return @c true.
569 virtual bool ContainsAll(const ICollection& collection) const;
572 * Compares the specified Object instance with the calling %ArrayList instance.
576 * @return @c true if the given object matches the calling List, @n
578 * @param[in] obj The object to compare with the calling list
579 * @remarks This method returns @c true only if the specified object @c obj is also an instance of %ArrayList class,
580 * both lists have the same size, and all the corresponding pairs of the elements in the two lists are equal.
581 * In other words, the two lists are equal if they contain the same elements in the same order.
583 virtual bool Equals(const Object& obj) const;
586 * Gets the hash value of the current instance.
590 * @return The hash value of the current instance
591 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
592 * the used hash function must generate a random distribution for all inputs.
594 virtual int GetHashCode(void) const;
597 * Distinguish between %ArrayList and LinkedList.
600 * @return @c true if it is an %ArrayList, @n
601 * else @c false if it is a LinkedList
603 virtual bool IsRandomAccessible(void) const
609 * Gets the element deleter of the collection.
613 * @return A function pointer to the existing element deleter
615 virtual DeleterFunctionType GetDeleter(void) const;
619 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
621 * @param[in] list The instance of the %ArrayList class to copy from
623 ArrayList(const ArrayList& list);
626 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
628 * @param[in] list An instance of %ArrayList
630 ArrayList& operator =(const ArrayList& list);
633 * Sorts the specified sub-list.
635 * @return An error code
636 * @param[in] startIndex The starting point of the sub-list to sort
637 * @param[in] endIndex The end point of the sub-list to sort
638 * @exception E_SUCCESS The method is successful.
639 * @exception E_INVALID_ARG A specified input parameter is invalid, or
640 * the comparer has failed to compare the elements.
642 result QuickSort(int startIndex, int endIndex);
645 * Sets the element deleter of the collection.
649 * @param[in] deleter A function pointer to the element deleter to set
651 virtual void SetDeleter(DeleterFunctionType deleter);
655 Object** __pObjArray;
657 IComparer* __pComparer;
658 static const int DEFAULT_CAPACITY = 10;
659 DeleterFunctionType __deleter;
661 friend class _ArrayListEnumerator;
662 friend class _ArrayListImpl;
663 class _ArrayListImpl* __pArrayListImpl;
667 }}} // Tizen::Base::Collection
669 #endif // _FBASE_COL_ARRAY_LIST_H_