//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
#include <FBaseColIHashCodeProvider.h>
#include <FBaseColIMultiMap.h>
-
namespace Tizen { namespace Base { namespace Collection
{
*
* @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 <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
*
*
* // Deallocates all objects
* // Because the destructor calls RemoveAll() internally, you do not need to call RemoveAll() to destroy all elements at the end.
- * map.RemoveAll();
+ * // map.RemoveAll();
* }
* @endcode
*/
*
* @since 2.0
*
- * @param[in] deleter The function pointer to type of the element deleter
- * @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
- * 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()
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
*
* @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()
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);
* @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);
* @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);
* @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 IEnumerator()
- * @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()
- * @see IMapEnumerator()
+ * @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;
* @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 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);
* @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()
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()
*
* @return @c true if the map contains the specified 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 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()
* @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;
* @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;
* Copies all the pairs from the specified map to this map.
*
* @return An error code
- * @param[in] map The map to copy
+ * @param[in] map The map to copy
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
* The @c map is modified during the operation of this method.
* @return An error code
* @param[in] newCapacity The new capacity @n
* It must be a power of two and be greater than current capacity.
- * @exception E_SUCCESS The method is successful.
+ * @exception E_SUCCESS The method is successful.
*/
result Resize(int newCapacity);