X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFBaseColHashMap.h;h=cf1434d51899bf045d283d38dab00c345b09db2d;hb=60d143778a54ae4c638a08d8c7304b099f70434e;hp=d7b99c2949e677c169a27431fd355238a9e7de8e;hpb=3b569ff3e66a065cb5728bc19d1da493c66f7583;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FBaseColHashMap.h b/inc/FBaseColHashMap.h index d7b99c2..cf1434d 100644 --- a/inc/FBaseColHashMap.h +++ b/inc/FBaseColHashMap.h @@ -43,7 +43,7 @@ class _HashMapEntry; * * For more information on the class features, see HashMap and MultiHashMap. * - * The following example demonstrates how to use the %HashMap class to create and initialize a %HashMap instance and to use its methods. + * The following example demonstrates how to use the %HashMap class to create and initialize a %HashMap instance and use its methods. * * @code * @@ -104,10 +104,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. + * It means that you do not transfer the ownership of the elements to the collection. * @see NoOpDeleter() * @see SingleObjectDeleter() * @see ArrayDeleter() @@ -122,7 +123,7 @@ public: virtual ~HashMap(void); /** - * Initializes an instance of an empty %HashMap class with the initial capacity and load factor. + * Initializes an instance of the empty %HashMap with the initial @c capacity and the load factor. * * @since 2.0 * @@ -130,34 +131,37 @@ 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, @n - * the @c capacity or the @c loadFactor is negative. - * @remarks The GetHashCode() method of key objects is used for hashing and - * the Equals() method of key objects is used for comparing keys. + * @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 objects is used for hashing and + * the Equals() method of the key objects is used for comparing the keys. * @see HashMap() */ result Construct(int capacity = 16, float loadFactor = 0.75); /** - * Initializes an instance of a %HashMap class by copying the elements of the specified @c map. + * Initializes an instance of %HashMap by copying the elements of the specified @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 - * @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 only the pointer; not the element itself. + * @param[in] map The map to copy + * @param[in] loadFactor The maximum ratio of elements to buckets + * @exception E_SUCCESS The method is successful. + * @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. * @see HashMap() */ result Construct(const IMap& map, float loadFactor = 0.75); /** - * Initializes an instance of an empty %HashMap class with the specified initial capacity, load factor, hash code provider, and comparer. + * Initializes an instance of the empty %HashMap with the specified initial capacity, load factor, hash code provider, and comparer. * * @since 2.0 * @@ -170,67 +174,71 @@ public: * @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 specified @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 HashMap() */ result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer); /** - * Initializes an instance of a %HashMap class by copying the elements of the specified map with the specified load factor, hash code provider, and comparer. + * Initializes an instance of %HashMap by copying the elements of the specified map with the specified load factor, hash code provider, and comparer. * * @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] 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 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] 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 only the pointer; not the element itself. - * @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 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 HashMap() */ result Construct(const IMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer); /** - * Adds the specified key-value pair to a map. + * Adds the specified key-value pair to the map. * * @since 2.0 * * @return An error code - * @param[in] pKey The pointer to key of the value to add - * @param[in] pValue The pointer to value to add + * @param[in] pKey A pointer to the key of the value to add + * @param[in] pValue A pointer to the value to add * @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. * @exception E_OBJ_ALREADY_EXIST The specified @c pKey already exists. - * @remarks This method performs a shallow copy. It adds only 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* pKey, Object* pValue); /** - * Gets an enumerator (an instance of the IMapEnumerator derived class) of this map. + * Gets the enumerator (an instance of the IMapEnumerator derived class) of this map. * * @since 2.0 * - * @return An instance of the IMapEnumerator derived class, if successful @n + * @return An instance of the IMapEnumerator derived class, @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 - * @see Tizen::Base::Collection::IMapEnumerator */ virtual IEnumerator* GetEnumeratorN(void) const; /** - * Gets the elements of the map in an instance of the IMapEnumerator derived class. + * Gets the elements of the map through an instance of the IMapEnumerator derived class. * * @since 2.0 * @@ -238,55 +246,56 @@ public: * else @c null if an exception occurs * @remarks The specific error code can be accessed using the GetLastResult() method. * @see Tizen::Base::Collection::IEnumerator - * @see Tizen::Base::Collection::IMapEnumerator */ virtual IMapEnumerator* GetMapEnumeratorN(void) const; /** - * Gets the value associated with the specified @c key. + * Gets the value associated to the specified @c key. * * @since 2.0 * - * @return The value associated with the key, @n + * @return The value associated to the key, @n * else @c null if an exception occurs - * @param[in] key The key to locate + * @param[in] key The key to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The 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: + * - 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. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetValue() */ virtual const Object* GetValue(const Object& key) const; /** - * Gets the value associated with the specified @c key. + * Gets the value associated to the specified @c key. * * @since 2.0 * - * @return The value associated with the key, @n + * @return The value associated to the key, @n * else @c null if an exception occurs - * @param[in] key The key to locate + * @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: + * - 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. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetValue() */ virtual Object* GetValue(const Object& key); /** - * Gets a list of all the keys in a map. + * Gets the list of all the keys in the map. * * @since 2.0 * - * @return A pointer to an IList object containing all the keys in the map, @n + * @return A pointer to the IList object containing all the keys in the map, @n * else @c null if an exception occurs - * @remarks The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method. - * 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. - * @see GetValuesN() + * @remarks + * - The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method. + * - 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. */ virtual IList* GetKeysN(void) const; @@ -295,25 +304,27 @@ public: * * @since 2.0 * - * @return A pointer to an IList object containing all the values in the map, @n + * @return A pointer to the IList object that contains all the values in the map, @n * else @c null if an exception occurs - * @remarks The IList stores just the pointers to the elements in the map, not the elements themselves. - * @remarks The specific error code can be accessed using the GetLastResult() method. + * @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; /** - * Removes the values associated with the specified @c key. + * Removes the values associated to the specified @c key. * * @since 2.0 * * @return An error code - * @param[in] key The key to remove + * @param[in] key The key to remove * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The 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); @@ -327,19 +338,19 @@ public: virtual void RemoveAll(void); /** - * Sets the value associated with the specified @c key by allocating it a new value. + * Sets the value associated to the specified @c key by allocating a new value to it. * * @since 2.0 * * @return An error code - * @param[in] key The key whose value is to replace - * @param[in] pValue The pointer to new value to replace + * @param[in] key The key whose value is replaced + * @param[in] pValue A pointer to the new value to replace * @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: + * - 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 To add a new key-value pair, use the Add() method. - * @see Add() * @see GetValue() */ virtual result SetValue(const Object& key, Object* pValue); @@ -360,10 +371,11 @@ public: * * @return @c true if the map contains the specified @c key, @n * else @c false - * @param[in] key The key to locate + * @param[in] key The key to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The 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: + * - The 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() */ @@ -383,14 +395,14 @@ public: virtual bool ContainsValue(const Object& value) const; /** - * Compares two instances of the %HashMap class. + * Compares two instances of %HashMap. * * @since 2.0 * * @return @c true if the two instances match, @n * else @c false * @param[in] obj The object to compare with the current instance - * @remarks This method returns @c true if and only if the two instances contain the same number of elements and all the elements contained in each other. + * @remarks This method returns @c true if and only if the two instances contain the same number of elements and all the elements are present in both of them. */ virtual bool Equals(const Object& obj) const; @@ -400,8 +412,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;