2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FBaseColArrayList.h
20 * @brief This is the header file for the %ArrayList class.
22 * This header file contains the declarations of the %ArrayList class.
24 #ifndef _FBASE_COL_ARRAY_LIST_H_
25 #define _FBASE_COL_ARRAY_LIST_H_
27 #include <FBaseObject.h>
28 #include <FBaseColIComparer.h>
29 #include <FBaseColIList.h>
32 namespace Tizen { namespace Base { namespace Collection
37 * @brief This class represents a collection of objects that can be individually accessed by an index.
42 * The %ArrayList class represents a collection of objects that can be individually accessed by an index.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/arraylist_linkedlist.htm">ArrayList and LinkedList</a>.
46 * The following example demonstrates how to use the %ArrayList class.
52 * using namespace Tizen::Base;
53 * using namespace Tizen::Base::Collection;
57 * MyClass::ArrayListSample(void)
59 * ArrayList list(SingleObjectDeleter);
63 * list.Add(new Integer(1)); // 1
64 * list.Add(new Integer(2)); // 1,2
65 * list.Add(new Integer(3)); // 1,2,3
67 * Integer* pInt = static_cast< Integer* > (list.GetAt(0));
69 * if (pInt->Equals(Integer(1)))
74 * list.InsertAt(new Integer(4), 1); // 1,4,2,3
76 * list.Remove(Integer(3)); // 1,4,2
78 * list.RemoveAt(0); // 4,2
80 * list.Sort(IntegerComparer()); // 2,4
82 * // Uses an enumerator to access elements in the list
83 * IEnumerator* pEnum = list.GetEnumeratorN();
84 * Object* pObj = null;
85 * while (pEnum->MoveNext() == E_SUCCESS)
87 * pObj = pEnum->GetCurrent();
93 * // Deallocates all objects
94 * // Because the destructor calls RemoveAll() internally, you do not need to call RemoveAll() to destroy all elements at the end.
95 * // list.RemoveAll();
99 class _OSP_EXPORT_ ArrayList
105 using IList::InsertAt;
107 using IList::RemoveAt;
108 using IList::RemoveItems;
109 using IList::RemoveAll;
111 using IList::ContainsAll;
113 * This is the default constructor for this class.
117 * @param[in] deleter The function pointer to type of the element deleter
118 * @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
119 * 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.
120 * It means that you do not transfer the ownership of elements to the collection.
121 * @remarks After creating an instance of the %ArrayList class, one of the Construct() methods must be called explicitly to initialize this instance.
123 * @see SingleObjectDeleter()
124 * @see ArrayDeleter()
126 explicit ArrayList(DeleterFunctionType deleter = NoOpDeleter);
129 * This destructor overrides Tizen::Base::Object::~Object().
133 virtual ~ArrayList(void);
136 * Initializes this instance of %ArrayList with the specified parameter and sets its initial capacity to the
141 * @return An error code
142 * @param[in] capacity The number of elements @n
143 * The default capacity is @c 10.
144 * @exception E_SUCCESS The method is successful.
145 * @exception E_INVALID_ARG A specified input parameter is invalid, or
146 * the specified @c capacity is negative.
147 * @remarks If the number of elements added to the list reaches the current capacity,
148 * the capacity is automatically increased by memory reallocation.
149 * Therefore, if the size of the list can be estimated,
150 * specifying the initial capacity eliminates the need to perform a number of
151 * resizing operations while adding elements to the list.
154 result Construct(int capacity = DEFAULT_CAPACITY);
158 * Initializes this instance of %ArrayList by copying the elements of the specified
160 * The capacity of the list is the same as the number of elements copied.
164 * @return An error code
165 * @param[in] collection A collection to add
166 * @exception E_SUCCESS The method is successful.
167 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
168 * the @c collection is modified during the operation of this method.
169 * @remarks This method performs a shallow copy. It copies just the pointer; not the element itself.
172 result Construct(const ICollection& collection);
175 * Adds the specified object to the end of this list.
179 * @return An error code
180 * @param[in] pObj An pointer to object to add
181 * @exception E_SUCCESS The method is successful.
182 * @exception E_INVALID_ARG The specified input parameter is invalid.
183 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
186 virtual result Add(Object* pObj);
190 * Adds the elements of the specified @c collection to the end of this list.
194 * @return An error code
195 * @param[in] collection A collection to add
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
198 * the @c collection is modified during the operation of this method.
199 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
202 virtual result AddItems(const ICollection& collection);
206 * Gets an enumerator (an instance of the IEnumerator-derived class) of this list.
210 * @return An instance of the IEnumerator-derived class, @n
211 * else @c null if some exception occurs
212 * @remarks The specific error code can be accessed using the GetLastResult() method.
214 virtual IEnumerator* GetEnumeratorN(void) const;
217 * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
221 * @return An instance of the IBidirectionalEnumerator derived class, @n
222 * else @c null if some exception occurs
223 * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
224 * to iterate over a collection (an instance of the IList derived class).
225 * The specific error code can be accessed using GetLastResult() method.
226 * @see Tizen::Base::Collection::IBidirectionalEnumerator
228 virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const;
231 * Gets the object at the specified @c index of this list.
235 * @return The object at the specified @c index of this list, @n
236 * else @c null if the index is not valid
237 * @param[in] index The index of the object in the calling list to read
238 * @exception E_SUCCESS The method is successful.
239 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure, or
240 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
241 * @remarks The specific error code can be accessed using the GetLastResult() method.
244 virtual const Object* GetAt(int index) const;
248 * Gets the object at the specified @c index of this list.
252 * @return The object at the specified @c index of this list, @n
253 * else @c null if the index is not valid
254 * @param[in] index The index of the object to read
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure, or
257 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
258 * @remarks The specific error code can be accessed using the GetLastResult() method.
261 virtual Object* GetAt(int index);
264 * Gets the IList within the specified range of this list.
268 * @return A pointer to IList, @n
269 * else @c null if some exception occurs
270 * @param[in] startIndex The starting index of the range
271 * @param[in] count The number of elements to read
272 * @exception E_SUCCESS The method is successful.
273 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
274 * - The specified index is outside the bounds of the data structure. @n
275 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
276 * - The @c count is greater than the number of elements starting from @c startIndex
278 * @remarks The IList stores just the pointers to the elements in the list, not the elements themselves.
279 * The specific error code can be accessed using the GetLastResult() method.
281 virtual IList* GetItemsN(int startIndex, int count) const;
284 * Searches for an object in this list. @n
285 * Gets the index of the object if found.
289 * @return An error code
290 * @param[in] obj The object to locate
291 * @param[out] index The index of the object
292 * @exception E_SUCCESS The method is successful.
293 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
296 virtual result IndexOf(const Object& obj, int& index) const;
299 * Searches for an object starting from the specified index. @n
300 * Gets the index of the object if found.
304 * @return An error code
305 * @param[in] obj The object to locate
306 * @param[in] startIndex The starting index for the search @n
307 * It must be less than the number of elements.
308 * @param[out] index The index of the object
309 * @exception E_SUCCESS The method is successful.
310 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
311 * the specified @c startIndex is either equal to or greater than the number of elements or less than @c 0.
312 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
315 virtual result IndexOf(const Object& obj, int startIndex, int& index) const;
318 * Searches for an object within the specified range. @n
319 * Gets the index of the object if found.
323 * @return An error code
324 * @param[in] obj The object to locate
325 * @param[in] startIndex The starting index of the range
326 * @param[in] count The number of elements to read
327 * @param[out] index The index of the object
328 * @exception E_SUCCESS The method is successful.
329 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
330 * - The specified index is outside the bounds of the data structure. @n
331 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
332 * - The @c count is greater than the number of elements starting from @c startIndex
334 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
337 virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const;
340 * Searches for the last occurrence of an object in this list. @n
341 * Gets the index of the object if found.
345 * @return An error code
346 * @param[in] obj The object to locate
347 * @param[out] index The index of the last occurrence of the specified object
348 * @exception E_SUCCESS The method is successful.
349 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
352 virtual result LastIndexOf(const Object& obj, int& index) const;
355 * Inserts the object at the specified location.
359 * @return An error code
360 * @param[in] pObj The pointer to object to insert
361 * @param[in] index The index at which the object must be inserted
362 * @exception E_SUCCESS The method is successful.
363 * @exception E_INVALID_ARG The specified input parameter is invalid.
364 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
365 * the @c index is greater than the number of elements or less than @c 0.
366 * @remarks The elements that follow the insertion point move down to accommodate the new element.
367 * If the @c index equals to the number of elements, then the new element
368 * is added at the end of this list.
369 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
373 virtual result InsertAt(Object* pObj, int index);
376 * Inserts the elements of the collection at the specified location.
380 * @return An error code
381 * @param[in] collection The collection to insert
382 * @param[in] startIndex The starting index at which the collection must be inserted
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
385 * the @c startIndex is greater than the number of elements or less than @c 0.
386 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
387 * the @c collection is modified during the operation of this method.
388 * @remarks The elements that follow the insertion point move down to accommodate the new element.
389 * If the @c startIndex equals to the number of elements then the new elements
390 * are added at the end of this list.
391 * This method performs a shallow copy. It inserts just the pointer; not the element itself.
395 virtual result InsertItemsFrom(const ICollection& collection, int startIndex);
398 * Removes the first occurrence of the specified object.
402 * @return An error code
403 * @param[in] obj An object to remove
404 * @exception E_SUCCESS The method is successful.
405 * @exception E_OBJ_NOT_FOUND The specified @c obj is not found.
410 virtual result Remove(const Object& obj);
413 * Removes the object at the specified location.
417 * @return An error code
418 * @param[in] index The index at which the object must be removed
419 * @exception E_SUCCESS The method is successful.
420 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
421 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
422 * @remarks The elements that follow the deletion point move up to occupy the vacated spot.
426 virtual result RemoveAt(int index);
429 * Removes all the elements within the specified range.
433 * @return An error code
434 * @param[in] startIndex The starting index of the range
435 * @param[in] count The number of elements to read
436 * @exception E_SUCCESS The method is successful.
437 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
438 * - The specified index is outside the bounds of the data structure. @n
439 * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n
440 * - The @c count is greater than the number of elements starting from @c startIndex
442 * @remarks The elements that follow the deletion point move up to occupy the vacated spot.
445 virtual result RemoveItems(int startIndex, int count);
448 * Removes all of the elements that are in the intersection of the specified @c collection
453 * @return An error code
454 * @param[in] collection The collection to remove from this list
455 * @exception E_SUCCESS The method is successful.
456 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
457 * the @c collection is modified during the operation of this method.
461 virtual result RemoveItems(const ICollection& collection);
464 * Removes all of the object pointers in the collection and also removes all of the objects depending on the specified element deleter.
465 * The %RemoveAll() can be called before the collection is deleted.
469 virtual void RemoveAll(void);
472 * Replaces the object at the specified @c index with the specified object.
476 * @return An error code
477 * @param[in] pObj An pointer to object to set
478 * @param[in] index The index at which the object must be set
479 * @exception E_SUCCESS The method is successful.
480 * @exception E_INVALID_ARG The specified input parameter is invalid.
481 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or
482 * the specified @c index is either equal to or greater than the number of elements or less than @c 0.
485 virtual result SetAt(Object* pObj, int index);
488 * Sets the capacity of this list to the specified value.
492 * @return An error code
493 * @param[in] newCapacity The new capacity of this list
494 * @exception E_SUCCESS The method is successful.
495 * @exception E_INVALID_ARG The specified input parameter is invalid, or
496 * the @c newCapacity is negative.
497 * @remarks When the new capacity is less than the current capacity, the elements
498 * within the truncated memory are not destroyed.
503 virtual result SetCapacity(int newCapacity);
506 * Sorts the elements of this list using the comparer provided.
510 * @return An error code
511 * @param[in] comparer The IComparer implementation to use when comparing elements
512 * @exception E_SUCCESS The method is successful.
513 * @exception E_INVALID_ARG The specified input parameter is invalid.
515 virtual result Sort(const IComparer& comparer);
518 * Sets the capacity to the actual number of elements in this list.
522 virtual void Trim(void);
525 * Gets the current capacity of this list.
529 * @return The current capacity of this list
532 virtual int GetCapacity(void) const;
535 * Gets the number of objects currently stored in this list.
539 * @return The number of objects currently stored in this list
541 virtual int GetCount(void) const;
544 * Checks whether a list contains the specified object.
548 * @return @c true if the object is present in the list, @n
550 * @param[in] obj The object to locate
553 virtual bool Contains(const Object& obj) const;
556 * Checks whether the list contains all the elements of the specified @c collection.
560 * @return @c true if the list contains all the elements of the specified @c collection, @n
562 * @param[in] collection The collection to check for in the list
563 * @exception E_SUCCESS The method is successful.
564 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or
565 * the @c collection is modified during the operation of this method.
566 * @remarks The specific error code can be accessed using the GetLastResult() method.
567 * @remarks If the given @c collection is empty, this method will return @c true.
570 virtual bool ContainsAll(const ICollection& collection) const;
573 * Compares the specified Object instance with the calling %ArrayList instance.
577 * @return @c true if the given object matches the calling List, @n
579 * @param[in] obj The object to compare with the calling list
580 * @remarks This method returns @c true only if the specified object @c obj is also an instance of %ArrayList class,
581 * both lists have the same size, and all the corresponding pairs of the elements in the two lists are equal.
582 * In other words, the two lists are equal if they contain the same elements in the same order.
584 virtual bool Equals(const Object& obj) const;
587 * Gets the hash value of the current instance.
591 * @return The hash value of the current instance
592 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
593 * the used hash function must generate a random distribution for all inputs.
595 virtual int GetHashCode(void) const;
598 * Distinguish between %ArrayList and LinkedList.
601 * @return @c true if it is an %ArrayList, @n
602 * else @c false if it is a LinkedList
604 virtual bool IsRandomAccessible(void) const
610 * Gets the element deleter of the collection.
614 * @return A function pointer to the existing element deleter
616 virtual DeleterFunctionType GetDeleter(void) const;
620 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
622 * @param[in] list The instance of the %ArrayList class to copy from
624 ArrayList(const ArrayList& list);
627 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
629 * @param[in] list An instance of %ArrayList
631 ArrayList& operator =(const ArrayList& list);
634 * Sorts the specified sub-list.
636 * @return An error code
637 * @param[in] startIndex The starting point of the sub-list to sort
638 * @param[in] endIndex The end point of the sub-list to sort
639 * @exception E_SUCCESS The method is successful.
640 * @exception E_INVALID_ARG A specified input parameter is invalid, or
641 * the comparer has failed to compare the elements.
643 result QuickSort(int startIndex, int endIndex);
646 * Sets the element deleter of the collection.
650 * @param[in] deleter A function pointer to the element deleter to set
652 virtual void SetDeleter(DeleterFunctionType deleter);
656 Object** __pObjArray;
658 IComparer* __pComparer;
659 static const int DEFAULT_CAPACITY = 10;
660 DeleterFunctionType __deleter;
662 friend class _ArrayListEnumerator;
663 friend class _ArrayListImpl;
664 class _ArrayListImpl* __pArrayListImpl;
668 }}} // Tizen::Base::Collection
670 #endif // _FBASE_COL_ARRAY_LIST_H_