X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFBaseColMultiHashMap.h;h=e17272db63f6f5d52c6c9b9a6f7d0b2cd64d811b;hb=60d143778a54ae4c638a08d8c7304b099f70434e;hp=78e728bc0bc6a5b49670d9250cfaa07755226345;hpb=3b569ff3e66a065cb5728bc19d1da493c66f7583;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FBaseColMultiHashMap.h b/inc/FBaseColMultiHashMap.h index 78e728b..e17272d 100644 --- a/inc/FBaseColMultiHashMap.h +++ b/inc/FBaseColMultiHashMap.h @@ -39,9 +39,9 @@ class _MultiHashMapEntry; * * @since 2.0 * - * The %MultiHashMap class represents a collection of associated keys and values that are organized based on the hash code of the key. - * There is no limit on the number of elements with the same key, but duplicated elements with the same key are not allowed. - * The key and value cannot be @c null. + * The %MultiHashMap class represents a collection of associated keys and values that are organized based on the hash code of the key. + * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed. + * The key and value cannot be a @c null. * @n * For more information on the class features, see HashMap and MultiHashMap. * @@ -114,10 +114,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 owning 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 the ownership of the elements is not transferred to the collection. * @see NoOpDeleter() * @see SingleObjectDeleter() * @see ArrayDeleter() @@ -132,7 +133,7 @@ public: virtual ~MultiHashMap(void); /** - * Initializes a new instance of %MultiHashMap with the specified capacity and load factor. + * Initializes a new instance of %MultiHashMap with the specified @c capacity and @c loadFactor. * * @since 2.0 * @@ -140,8 +141,9 @@ public: * @param[in] capacity The initial capacity * @param[in] loadFactor The maximum ratio of elements to buckets * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the @c capacity or the @c loadFactor is negative. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The specified @c capacity or the specified @c loadFactor is negative. * @remarks The GetHashCode() method of the key object is used for hashing and the * Equals() method of the key object is used for comparing the keys. * @see MultiHashMap() @@ -149,19 +151,20 @@ public: result Construct(int capacity = 16, float loadFactor = 0.75); /** - * Initializes a new instance of %MultiHashMap by copying the elements of the given map. + * Initializes a new instance of %MultiHashMap by copying the elements of the given @c map. * * @since 2.0 * * @return An error code - * @param[in] map The map to copy - * @param[in] loadFactor The maximum ratio of elements to buckets @n - * If it is @c 0, the default load factor(0.75) is used. + * @param[in] map The map to copy + * @param[in] loadFactor The maximum ratio of elements to buckets @n + * If it is @c 0, the default load factor(0.75) is used. * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c loadFactor is negative. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c map is modified during the operation of this method. - * @remarks This method performs a shallow copy. It copies 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 map is modified during the operation of this method. + * @remarks This method performs a shallow copy. It copies just the pointer and not the element itself. * @see MultiHashMap() */ result Construct(const IMultiMap& map, float loadFactor = 0.75); @@ -173,17 +176,18 @@ public: * @since 2.0 * * @return An error code - * @param[in] capacity The initial capacity @n - * If it is @c 0, the default capacity (16) is used. - * @param[in] loadFactor The maximum ratio of elements to buckets @n - * If it is @c 0, the default load factor (0.75) is used. - * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes - * for all keys in this map - * @param[in] comparer An instance of the IComparer derived class to use when comparing keys + * @param[in] capacity The initial capacity @n + * If it is @c 0, the default capacity (16) is used. + * @param[in] loadFactor The maximum ratio of elements to buckets @n + * If it is @c 0, the default load factor (0.75) is used. + * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes + * for all the keys in this map + * @param[in] comparer An instance of the IComparer derived class to use when comparing the keys * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the @c capacity or the @c loadFactor is negative. - * @remarks The instances of hash code provider and comparer will not be deallocated later from this map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The specfied @c capacity or the specified @c loadFactor is negative. + * @remarks The instances of the hash code provider and the comparer are not deallocated later from this map. * @see MultiHashMap() */ result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer); @@ -195,19 +199,22 @@ public: * @since 2.0 * * @return An error code - * @param[in] map A map to copy - * @param[in] loadFactor The maximum ratio of elements to buckets @n - * If it is @c 0, the default load factor (0.75) is used. - * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes - * for all keys in this map - * @param[in] comparer An instance of the IComparer derived class to use when comparing keys + * @param[in] map A map to copy + * @param[in] loadFactor The maximum ratio of elements to buckets @n + * If it is @c 0, the default load factor (0.75) is used. + * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes + * for all the keys in this map + * @param[in] comparer An instance of the IComparer derived class to use when comparing the keys * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the @c loadFactor is negative. - * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation, or - * the @c map is modified during the operation of this method. - * @remarks This method performs a shallow copy. It copies just the pointer; not the element itself. - * The instances of hash code provider and comparer will not be deallocated later from this map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The specified @c loadFactor is negative. + * @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 map is modified during the operation of this method. + * @remarks + * - This method performs a shallow copy. It copies just the pointer and not the element itself. + * - The instances of the hash code provider and the comparer are not deallocated later from this map. * @see MultiHashMap() */ result Construct(const IMultiMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer); @@ -218,80 +225,88 @@ public: * @since 2.0 * * @return An error code - * @param[in] pKey The pointer to key to add - * @param[in] pValue The pointer to corresponding value to add + * @param[in] pKey A pointer to the key to add + * @param[in] pValue A pointer to the corresponding value to add * @exception E_SUCCESS The method is successful. * @exception E_OBJ_ALREADY_EXIST The specified pair of @c pKey and @c pValue already exists. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see Remove() */ virtual result Add(Object* pKey, Object* pValue); /** - * Gets an enumerator of this map. + * Gets the enumerator of this map. * * @since 2.0 * - * @return An enumerator (an instance of the IEnumerator derived class) of this map, @n - * else @c null if some exception occurs - * @remarks If the key has multiple values, the enumeration proceeds as follows: {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... - * The specific error code can be accessed using the GetLastResult() method. - * @see IMapEnumerator + * @return The enumerator (an instance of the IEnumerator derived class) of this map, @n + * else @c null if an exception occurs + * @remarks + * - If the key has multiple values, the enumeration proceeds as follows: + * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... + * - The specific error code can be accessed using the GetLastResult() method. + * @see IMapEnumerator() */ virtual IEnumerator* GetEnumeratorN(void) const; /** - * Gets an enumerator of this map. + * Gets the enumerator of this map. * * @since 2.0 * - * @return An enumerator (an instance of the IMapEnumerator derived class) of this map, @n - * else @c null if some exception occurs - * @remarks If the key has multiple values, the enumeration proceeds as follows: {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... - * The specific error code can be accessed using the GetLastResult() method. - * @see IEnumerator + * @return The enumerator (an instance of the IMapEnumerator derived class) of this map, @n + * else @c null if an exception occurs + * @remarks + * - If the key has multiple values, the enumeration proceeds as follows: + * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... + * - The specific error code can be accessed using the GetLastResult() method. + * @see IEnumerator() */ virtual IMapEnumerator* GetMapEnumeratorN(void) const; /** - * Gets an enumerator of the values associated with the specified key. + * Gets the enumerator of the values associated with the specified key. * * @since 2.0 * - * @return An enumerator (an instance of the IEnumerator derived class) of the values associated with the specified key, @n - * else @c null if some exception occurs - * @param[in] key A key to locate + * @return The enumerator (an instance of the IEnumerator derived class) of the values associated with the specified key, @n + * else @c null if an exception occurs + * @param[in] key The key to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetValue() */ virtual IEnumerator* GetValuesN(const Object& key) const; /** - * Gets a list of all unique keys in this map. + * Gets a list of all the unique keys in this map. * * @since 2.0 * - * @return A list of all unique keys in this map - * @remarks The %IList stores just the pointers to the elements in the map, not the elements themselves. - * The specific error code can be accessed using the GetLastResult() method. + * @return The list of all the unique keys in this map + * @remarks + * - The IList stores just the pointers to the elements in the map and not the elements themselves. + * - The specific error code can be accessed using the GetLastResult() method. * @see GetValuesN() */ virtual IList* GetKeysN(void) const; /** - * Gets a list of all the values in this map. + * Gets the list of all the values in this map. * * @since 2.0 * - * @return A list of all the values in this map - * @remarks The IList stores just the pointers to the elements in the map, not the elements themselves. - * The specific error code can be accessed using the GetLastResult() method. + * @return The list of all the values in this map + * @remarks + * - The IList stores just the pointers to the elements in the map and not the elements themselves. + * - The specific error code can be accessed using the GetLastResult() method. * @see GetKeysN() */ virtual IList* GetValuesN(void) const; @@ -304,9 +319,10 @@ public: * @return An error code * @param[in] key The key to remove * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. * @see Add() */ virtual result Remove(const Object& key); @@ -317,39 +333,41 @@ public: * @since 2.0 * * @return An error code - * @param[in] key The key whose mapping is to remove from the map - * @param[in] value The value to remove + * @param[in] key The key whose mapping is removed from the map + * @param[in] value The value to remove * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair has not been found in the map. * @remarks The specified key is also removed if there are no more values associated with it. * @see Add() */ virtual result Remove(const Object& key, const Object& value); /** - * Removes all the object pointers in the @c collection. @n + * Removes all the object pointers in the collection. @n * * @since 2.0 * - * @remarks This method can be called before deleting @c collection. + * @remarks This method can be called before deleting the collection. */ virtual void RemoveAll(void); /** - * Sets the value associated with the given key with a new value. + * Sets the value associated with the given key to a new value. * * @since 2.0 * * @return An error code - * @param[in] key The key for which the associated value needs to replace - * @param[in] value The value to replace - * @param[in] pNewValue The pointer to new value to replace the existing value + * @param[in] key The key for which the associated value is replaced + * @param[in] value The value to replace + * @param[in] pNewValue A pointer to the new value that replaces the existing value * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair has not been found in the map. * @remarks To add a new key-value pair, use the Add() method. * @see Add() * @see GetValuesN() @@ -366,32 +384,34 @@ public: virtual int GetCount(void) const; /** - * Gets the number of values whose key matches the key. + * Gets the number of values whose key matches the given key. * * @since 2.0 * * @return An error code - * @param[in] key A key to locate - * @param[out] count The number of values whose key is the @c key + * @param[in] key A key to locate + * @param[out] count The number of values whose key matches the given key * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. */ virtual result GetCount(const Object& key, int& count) const; /** - * Checks whether the map contains the specified key and value. + * Checks whether the map contains the specified key and value pair. * * @since 2.0 * * @return @c true if the map contains the specified key and value pair, @n * else @c false - * @param[in] key The key to locate - * @param[in] value The value to locate + * @param[in] key The key to locate + * @param[in] value The value to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see ContainsKey() * @see ContainsValue() @@ -407,8 +427,9 @@ public: * else @c false * @param[in] key The key to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see ContainsValue() * @see Contains() @@ -437,8 +458,8 @@ public: * @return @c true if the two instances are equal, @n * @c false * @param[in] obj The object to compare with the current instance - * @remarks This method returns @c true only if the specified object is also an instance of %MultiHashMap class, - * both maps have the same number of elements, and both maps contain the same elements. + * @remarks This method returns @c true only if the specified object is also an instance of the %MultiHashMap class, + * both the maps have the same number of elements, and both the maps contain the same elements. */ virtual bool Equals(const Object& obj) const; @@ -448,8 +469,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;