X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFBaseColLinkedList.h;h=037b60e2b67490d9339b125fd0826b31da96d151;hb=376b1791f5888970901326fa60f67431fa701a4d;hp=e6a24c65ec936cf08f854b1927a08f4718ea7f3c;hpb=f8d74dfbe5576485c343916da07fb7382a1fac98;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FBaseColLinkedList.h b/inc/FBaseColLinkedList.h index e6a24c6..037b60e 100644 --- a/inc/FBaseColLinkedList.h +++ b/inc/FBaseColLinkedList.h @@ -33,11 +33,11 @@ class _ListNode; /** * @class LinkedList - * @brief This class represents a collection of objects that can be individually accessed by index. + * @brief This class represents a collection of objects that can be individually accessed by an index. * * @since 2.0 * - * The %LinkedList class represents a collection of objects that can be individually accessed by index. + * The %LinkedList class represents a collection of objects that can be individually accessed by an index. * * For more information on the class features, see ArrayList and LinkedList. * @@ -107,10 +107,11 @@ public: * * @since 2.0 * - * @param[in] deleter The function pointer to type of the element deleter - * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter. This gives the collection the ownership of elements and the collection will destroy elements. @n - * 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. - * It means that you do not transfer the ownership of elements to the collection. + * @param[in] deleter A function pointer to the type of the element deleter + * @remarks To create an owing collection, set the element deleter value as @c SingleObjectDeleter. @n + * This gives the collection the ownership of the elements and the collection destroys the elements. @n + * 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 + * It means that you do not transfer the ownership of the elements to the collection. * @see NoOpDeleter() * @see SingleObjectDeleter() * @see ArrayDeleter() @@ -130,10 +131,10 @@ public: * @since 2.0 * * @return An error code - * @param[in] pObj An pointer to object to add + * @param[in] pObj A pointer to the object to add * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified input parameter is invalid. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see Remove() */ virtual result Add(Object* pObj); @@ -144,157 +145,168 @@ public: * @since 2.0 * * @return An error code - * @param[in] collection A collection to add + * @param[in] collection The collection to add * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c collection is modified during the operation of this method. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The current state of the instance prohibits the execution of the specified operation. + * - The specified @c collection is modified during the operation of this method. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see RemoveItems() */ virtual result AddItems(const ICollection& collection); /** - * Gets an enumerator (an instance of the IEnumerator derived class) to the list. + * Gets the enumerator (an instance of the IEnumerator derived class) of the list. * * @since 2.0 * - * @return An enumerator of the calling list object, @n + * @return The enumerator of the calling list object, @n * else @c null if an exception occurs * @remarks The specific error code can be accessed using the GetLastResult() method. - * @see Tizen::Base::Collection::IEnumerator */ virtual IEnumerator* GetEnumeratorN(void) const; /** - * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list. + * Gets the bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of the list. * * @since 2.0 * * @return An instance of the IBidirectionalEnumerator derived class, @n - * else @c null if some exception occurs - * @remarks Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) + * else @c null if an exception occurs + * @remarks + * - Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) * to iterate over a collection (an instance of the IList derived class). - * The specific error code can be accessed using GetLastResult() method. - * @see Tizen::Base::Collection::IBidirectionalEnumerator + * - The specific error code can be accessed using GetLastResult() method. */ virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const; /** - * Gets the object at the specified index of the calling list. + * Gets the object at the specified @c index of the calling list. * * @since 2.0 * * @return A pointer to the object at the specified index of the list, @n - * else @c null if the index is not valid + * else @c null if the index is invalid * @param[in] index The index of the object to read * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c index is equal to or greater than the number of elements or less than @c 0. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c index is either greater than or equal to the number of elements. + * - The specified @c index is less than @c 0. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetAt() */ virtual const Object* GetAt(int index) const; /** - * Gets the object at the specified index of the calling list. + * Gets the object at the specified @c index of the calling list. * * @since 2.0 * * @return A pointer to the object at the specified index of the list, @n - * else @c null if the index is not valid + * else @c null if the index is invalid * @param[in] index The index of the object to read * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c index is equal to or greater than the number of elements or less than @c 0. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c index is either greater than or equal to the number of elements. + * - The specified @c index is less than @c 0. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetAt() */ virtual Object* GetAt(int index); /** - * Gets an IList with the specified range from the calling list object. + * Gets the IList with the specified range from the calling list object. * * @since 2.0 * - * @return An IList pointer if successful, @n + * @return An IList pointer , @n * else @c null if an exception occurs - * @param[in] startIndex The starting index of the range - * @param[in] count The number of elements to read + * @param[in] startIndex The starting index of the range + * @param[in] count The number of elements to read * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n - * - The specified index is outside the bounds of the data structure. @n - * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n - * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0. - * @remarks The IList stores just the pointers to the elements in the list, not the elements themselves. - * The specific error code can be accessed using the GetLastResult() method. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c startIndex is either greater than or equal to the number of elements. + * - The specified @c startIndex is less than @c 0. + * - The specified @c count is either greater than the number of elements starting from @c startIndex. + * - The specified @c count is less than @c 0. + * @remarks + * - The IList stores just the pointers to the elements in the list and not the elements themselves. + * - The specific error code can be accessed using the GetLastResult() method. */ virtual IList* GetItemsN(int startIndex, int count) const; /** * Searches for an object in this list. @n - * Gets the index of the object if found. + * Gets the @c index of the object if found. * * @since 2.0 * * @return An error code - * @param[in] obj The object to locate - * @param[out] index The index of the object + * @param[in] obj The object to locate + * @param[out] index The index of the object * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The specified @c obj is not found. + * @exception E_OBJ_NOT_FOUND The specified @c obj has not been found. */ virtual result IndexOf(const Object& obj, int& index) const; /** - * Searches for an object starting from the specified index. @n - * Gets the index of the object if found. + * Searches for an object starting from the specified @c startIndex. @n + * Gets the @c index of the object if found. * * @since 2.0 * * @return An error code - * @param[in] obj The object to locate - * @param[in] startIndex The starting index for the search @n - * It must be less than the number of elements. - * @param[out] index The index of the object + * @param[in] obj The object to locate + * @param[in] startIndex The starting index for the search @n + * It must be less than the number of elements. + * @param[out] index The index of the object * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. - * @exception E_OBJ_NOT_FOUND The specified @c obj is not found. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c startIndex is either greater than or equal to the number of elements in the list. + * - The specified @c startIndex is less than @c 0. + * @exception E_OBJ_NOT_FOUND The specified @c obj has not been found. * @see LastIndexOf() */ virtual result IndexOf(const Object& obj, int startIndex, int& index) const; /** * Searches for an object within the specified range. @n - * Gets the index of the object if found. + * Gets the @c index of the object if found. * * @since 2.0 * * @return An error code - * @param[in] obj The object to locate - * @param[in] startIndex The starting index of the range - * @param[in] count The number of elements to read - * @param[out] index The index of the object + * @param[in] obj The object to locate + * @param[in] startIndex The starting index of the range + * @param[in] count The number of elements to read + * @param[out] index The index of the object * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n - * - The specified index is outside the bounds of the data structure. @n - * - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n - * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0. - * @exception E_OBJ_NOT_FOUND The specified @c obj is not found. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c startIndex is either greater than or equal to the number of elements in the list. + * - The specified @c startIndex is less than @c 0. + * - The specified @c count is greater than the number of elements starting from @c startIndex. + * - The specified @c count is less than @c 0. + * @exception E_OBJ_NOT_FOUND The specified @c obj has not been found. * @see LastIndexOf() */ virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const; /** * Searches for the last occurrence of an object in this list. @n - * Gets the index of the object if found. + * Gets the @c index of the object if found. * * @since 2.0 * * @return An error code - * @param[in] obj The object to locate - * @param[out] index The index of the last occurrence of the specified object + * @param[in] obj The object to locate + * @param[out] index The index of the last occurrence of the specified object * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The specified @c obj is not found. + * @exception E_OBJ_NOT_FOUND The specified @c obj has not been found. * @see IndexOf() */ virtual result LastIndexOf(const Object& obj, int& index) const; @@ -305,15 +317,18 @@ public: * @since 2.0 * * @return An error code - * @param[in] pObj The pointer to object to insert - * @param[in] index The index at which the object must be inserted + * @param[in] pObj A pointer to the object to insert + * @param[in] index The index at which the object is inserted * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c index is greater than the number of elements or less than @c 0. - * @remarks If the @c index equals to the number of elements, then the new element + * @exception E_INVALID_ARG A specified input parameter is invalid. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c index is greater than the number of elements. + * - The specified @c index is less than @c 0. + * @remarks + * - If the @c index is equal to the number of elements, then the new elements * is added at the end of this list. - * This method performs a shallow copy. It inserts just the pointer; not the element itself. + * - This method performs a shallow copy. It inserts just the pointer and not the element itself. * @see Add() * @see RemoveAt() */ @@ -325,16 +340,20 @@ public: * @since 2.0 * * @return An error code - * @param[in] collection The collection to insert elements from - * @param[in] startIndex The starting index at which the elements must be inserted + * @param[in] collection The collection to insert elements from + * @param[in] startIndex The starting index at which the elements are inserted * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c startIndex is either greater than the number of elements or less than @c 0. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c collection is modified during the operation of this method. - * @remarks If the @c startIndex equals to the number of elements then the new elements - * are added at the end of this list. - * This method performs a shallow copy. It inserts just the pointer; not the element itself. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified index is outside the bounds of the data structure. + * - The specified @c startIndex is greater than the number of elements. + * - The specified @c startIndex is less than @c 0. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The current state of the instance prohibits the execution of the specified operation. + * - The specified @c collection is modified during the operation of this method. + * @remarks + * - If the specified @c startIndex is equal to the number of elements, then the new elements + * are added at the end of this list. + * - This method performs a shallow copy. It inserts just the pointer and not the element itself. * @see RemoveItems() * @see AddItems() */ @@ -346,9 +365,9 @@ public: * @since 2.0 * * @return An error code - * @param[in] obj An object to remove + * @param[in] obj The object to remove * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The specified @c obj is not found. + * @exception E_OBJ_NOT_FOUND The specified @c obj has not been found. * @see Add() * @see RemoveAt() */ @@ -360,27 +379,31 @@ public: * @since 2.0 * * @return An error code - * @param[in] index The index at which the object must be removed + * @param[in] index The index at which the object is removed * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * The specified @c index is equal to or greater than the number of elements or less than @c 0. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c index is either greater than or equal to the number of elements. + * - The specified @c index is less than @c 0. * @see InsertAt() */ virtual result RemoveAt(int index); /** - * Removes all elements within the specified range from the list. + * Removes all the elements within the specified range from the list. * * @since 2.0 * * @return An error code - * @param[in] startIndex The starting index of the range - * @param[in] count The number of element to remove + * @param[in] startIndex The starting index of the range + * @param[in] count The number of elements to remove * @exception E_SUCCESS The method is successful. - * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n - * - The specified index is outside the bounds of the data structure. @n - * - The specified @c startIndex is either equal to or greater than the number of elements or less than @c 0. @n - * - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c startIndex is either greater than or equal to the number of elements. + * - The specified @c startIndex is less than @c 0. + * - The specified @c count is greater than the number of elements starting from @c startIndex. + * - The specified @c count is less than @c 0. * @see AddItems() * @see InsertItemsFrom() */ @@ -395,8 +418,9 @@ public: * @return An error code * @param[in] collection The collection to remove from this list * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c collection is modified during the operation of this method. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The current state of the instance prohibits the execution of the specified operation. + * - The specified @c collection is modified during the operation of this method. * @see Remove() * @see RemoveAt() */ @@ -404,7 +428,7 @@ public: /** - * Removes all of the object pointers in the collection and also removes all of the objects depending on the specified element deleter. + * Removes all of the object pointers in the collection and also removes all the objects depending on the specified element deleter. * This method can be called before deleting the objects in a collection. * * @since 2.0 @@ -413,31 +437,34 @@ public: virtual void RemoveAll(void); /** - * Replaces the object at the specified index with the given object. + * Replaces the object at the specified @c index with the given object. * * @since 2.0 * * @return An error code - * @param[in] pObj The pointer to object to set - * @param[in] index The index at which the object must be set + * @param[in] pObj A pointer to the object to set + * @param[in] index The index at which the object is set * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid. - * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure, or - * the specified @c index is equal to or greater than the number of elements or less than @c 0. + * @exception E_INVALID_ARG A specified input parameter is invalid. + * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: + * - The specified @c index is outside the bounds of the data structure. + * - The specified @c index is either greater than or equal to the number of elements. + * - The specified @c index is less than @c 0. * @see GetAt() */ virtual result SetAt(Object* pObj, int index); /** - * Sorts the elements of this list using the comparer provided. + * Sorts the elements of this list using the @c comparer provided. * * @since 2.0 * * @return An error code - * @param[in] comparer The IComparer implementation to use when comparing elements + * @param[in] comparer The IComparer implementation to use when comparing the elements * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid, or - * the @c comparer is not valid. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The specified @c comparer is invalid. */ virtual result Sort(const IComparer& comparer); @@ -463,18 +490,20 @@ public: virtual bool Contains(const Object& obj) const; /** - * Checks whether the list contains all the elements of the specified collection. + * Checks whether the list contains all the elements of the specified @c collection. * * @since 2.0 * - * @return @c true if this list contains all of the elements in the specified collection, @n + * @return @c true if this list contains all the elements in the specified collection, @n * else @c false * @param[in] collection The collection to check for containment in this list * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c collection is modified during the operation of this method. - * @remarks The specific error code can be accessed using the GetLastResult() method. - * @remarks If the given @c collection is empty, this method will return @c true. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The current state of the instance prohibits the execution of the specified operation. + * - The @c collection is modified during the operation of this method. + * @remarks + * - The specific error code can be accessed using the GetLastResult() method. + * - If the given @c collection is empty, this method returns @c true. * @see Contains() */ virtual bool ContainsAll(const ICollection& collection) const; @@ -487,9 +516,10 @@ public: * @return @c true if the specified instance equals the current instance, @n * else @c false * @param[in] obj The object to compare with the calling object - * @remarks This method returns @c true only if the specified object is also an instance of the %LinkedList class, + * @remarks + * - This method returns @c true only if the specified object is also an instance of the %LinkedList class, * both lists have the same size, and all corresponding pairs of elements in the two lists are equal. - * In other words, two lists are equal if they contain the same elements in the same order. + * - In other words, two lists are equal if they contain the same elements in the same order. */ virtual bool Equals(const Object& obj) const; @@ -499,8 +529,8 @@ public: * @since 2.0 * * @return The hash value of the current instance - * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n - * the used hash function must generate a random distribution for all inputs. + * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. @n + * For better performance, the used hash function must generate a random distribution for all the inputs. */ virtual int GetHashCode(void) const; @@ -574,7 +604,7 @@ private: /** * Gets a node from Available node list. * - * @return A pointer to a new List Node if successful, @n + * @return A pointer to a new List Node, @n * else @c null if no node is available */ _ListNode* GetNewNode(void);