2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FBaseColMultiHashMap.h
19 * @brief This is the header file for the %MultiHashMap class.
21 * This header file contains the declarations of the %MultiHashMap class.
23 #ifndef _FBASE_COL_MULTI_HASH_MAP_H_
24 #define _FBASE_COL_MULTI_HASH_MAP_H_
26 #include <FBaseObject.h>
27 #include <FBaseColIComparer.h>
28 #include <FBaseColIHashCodeProvider.h>
29 #include <FBaseColIMultiMap.h>
31 namespace Tizen { namespace Base { namespace Collection
34 class _MultiHashMapEntry;
38 * @brief This class represents a collection of associated keys and values that are organized based on the hash code of the key.
42 * The %MultiHashMap class represents a collection of associated keys and values that are organized based on the hash code of the key.
43 * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed.
44 * The key and value cannot be a @c null.
46 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
48 * The following example demonstrates how to use the %MultiHashMap class.
53 * using namespace Tizen::Base;
54 * using namespace Tizen::Base::Collection;
57 * MyClass::MultiHashMapSample(void)
59 * MultiHashMap map(SingleObjectDeleter);
61 * // Constructs a MultiHashMap instance with default values for capacity, load factor, hash code provider, and comparer
64 * map.Add(new String(L"Zero"), new Integer(0)); // map.GetCount() : 1, map : (Zero -> 0)
65 * map.Add(new String(L"One"), new Integer(1)); // map.GetCount() : 2, map : (Zero -> 0), (one -> 1)
66 * map.Add(new String(L"Two"), new Integer(2)); // map.GetCount() : 3, map : (Zero -> 0), (one -> 1), (Two -> 2)
67 * map.Add(new String(L"Two"), new Integer(20)); // map.GetCount() : 4, map : (Zero -> 0), (One -> 1), (Two -> 2, 20)
69 * // Gets values with the specified key
70 * Integer* pValue = null;
71 * IEnumerator *pValueEnum = map.GetValuesN(String(L"Two"));
72 * while(pValueEnum->MoveNext() == E_SUCCESS)
74 * pValue = static_cast< Integer* > (pValueEnum->GetCurrent());
79 * // Removes values with the specified key // String(L"Two"), Integer(2), Integer(20) are removed
80 * map.Remove(String(L"Two"));
82 * // Uses an enumerator to access elements in the map
83 * IMapEnumerator* pMapEnum = map.GetMapEnumeratorN();
84 * String* pKey = null;
85 * while (pMapEnum->MoveNext() == E_SUCCESS)
87 * pKey = static_cast< String* > (pMapEnum->GetKey());
88 * pValue = static_cast< Integer* > (pMapEnum->GetValue());
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.
99 class _OSP_EXPORT_ MultiHashMap
104 using IMultiMap::Add;
105 using IMultiMap::Remove;
106 using IMultiMap::RemoveAll;
107 using IMultiMap::SetValue;
108 using IMultiMap::Contains;
109 using IMultiMap::ContainsKey;
112 * The object is not fully constructed after this constructor is called. For full construction, @n
113 * the Construct() method must be called right after calling this constructor.
117 * @param[in] deleter A function pointer to the type of the element deleter
118 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
119 * This gives the collection the ownership of the elements and the collection destroys the elements. @n
120 * 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
121 * It means that the ownership of the elements is not transferred to the collection.
123 * @see SingleObjectDeleter()
124 * @see ArrayDeleter()
126 explicit MultiHashMap(DeleterFunctionType deleter = NoOpDeleter);
129 * This destructor overrides Tizen::Base::Object::~Object().
133 virtual ~MultiHashMap(void);
136 * Initializes a new instance of %MultiHashMap with the specified @c capacity and @c loadFactor.
140 * @return An error code
141 * @param[in] capacity The initial capacity
142 * @param[in] loadFactor The maximum ratio of elements to buckets
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_INVALID_ARG Either of the following conditions has occurred:
145 * - A specified input parameter is invalid.
146 * - The specified @c capacity or the specified @c loadFactor is negative.
147 * @remarks The GetHashCode() method of the key object is used for hashing and the
148 * Equals() method of the key object is used for comparing the keys.
149 * @see MultiHashMap()
151 result Construct(int capacity = 16, float loadFactor = 0.75);
154 * Initializes a new instance of %MultiHashMap by copying the elements of the given @c map.
158 * @return An error code
159 * @param[in] map The map to copy
160 * @param[in] loadFactor The maximum ratio of elements to buckets @n
161 * If it is @c 0, the default load factor(0.75) is used.
162 * @exception E_SUCCESS The method is successful.
163 * @exception E_INVALID_ARG The specified @c loadFactor is negative.
164 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
165 * - The current state of the instance prohibits the execution of the specified operation.
166 * - The specified @c map is modified during the operation of this method.
167 * @remarks This method performs a shallow copy. It copies just the pointer and not the element itself.
168 * @see MultiHashMap()
170 result Construct(const IMultiMap& map, float loadFactor = 0.75);
174 * Initializes a new instance of the %MultiHashMap class, with the specified initial capacity, load factor, hash code provider, and comparer.
178 * @return An error code
179 * @param[in] capacity The initial capacity @n
180 * If it is @c 0, the default capacity (16) is used.
181 * @param[in] loadFactor The maximum ratio of elements to buckets @n
182 * If it is @c 0, the default load factor (0.75) is used.
183 * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes
184 * for all the keys in this map
185 * @param[in] comparer An instance of the IComparer derived class to use when comparing the keys
186 * @exception E_SUCCESS The method is successful.
187 * @exception E_INVALID_ARG Either of the following conditions has occurred:
188 * - A specified input parameter is invalid.
189 * - The specfied @c capacity or the specified @c loadFactor is negative.
190 * @remarks The instances of the hash code provider and the comparer are not deallocated later from this map.
191 * @see MultiHashMap()
193 result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
196 * Initializes a new instance of the %MultiHashMap class by copying the elements of the specified map,
197 * with the specified load factor, hash code provider, and comparer.
201 * @return An error code
202 * @param[in] map A map to copy
203 * @param[in] loadFactor The maximum ratio of elements to buckets @n
204 * If it is @c 0, the default load factor (0.75) is used.
205 * @param[in] provider An instance of the IHashCodeProvider derived class that supplies the hash codes
206 * for all the keys in this map
207 * @param[in] comparer An instance of the IComparer derived class to use when comparing the keys
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_INVALID_ARG Either of the following conditions has occurred:
210 * - A specified input parameter is invalid.
211 * - The specified @c loadFactor is negative.
212 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
213 * - The current state of the instance prohibits the execution of the specified operation.
214 * - The specified @c map is modified during the operation of this method.
216 * - This method performs a shallow copy. It copies just the pointer and not the element itself.
217 * - The instances of the hash code provider and the comparer are not deallocated later from this map.
218 * @see MultiHashMap()
220 result Construct(const IMultiMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
223 * Adds the specified key-value pair to this map.
227 * @return An error code
228 * @param[in] pKey A pointer to the key to add
229 * @param[in] pValue A pointer to the corresponding value to add
230 * @exception E_SUCCESS The method is successful.
231 * @exception E_OBJ_ALREADY_EXIST The specified pair of @c pKey and @c pValue already exists.
232 * @exception E_INVALID_ARG Either of the following conditions has occurred:
233 * - A specified input parameter is invalid.
234 * - The comparer has failed to compare the keys.
235 * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself.
238 virtual result Add(Object* pKey, Object* pValue);
241 * Gets the enumerator of this map.
245 * @return The enumerator (an instance of the IEnumerator derived class) of this map, @n
246 * else @c null if an exception occurs
248 * - If the key has multiple values, the enumeration proceeds as follows:
249 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
250 * - The specific error code can be accessed using the GetLastResult() method.
251 * @see IMapEnumerator()
253 virtual IEnumerator* GetEnumeratorN(void) const;
256 * Gets the enumerator of this map.
260 * @return The enumerator (an instance of the IMapEnumerator derived class) of this map, @n
261 * else @c null if an exception occurs
263 * - If the key has multiple values, the enumeration proceeds as follows:
264 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
265 * - The specific error code can be accessed using the GetLastResult() method.
268 virtual IMapEnumerator* GetMapEnumeratorN(void) const;
271 * Gets the enumerator of the values associated with the specified key.
275 * @return The enumerator (an instance of the IEnumerator derived class) of the values associated with the specified key, @n
276 * else @c null if an exception occurs
277 * @param[in] key The key to locate
278 * @exception E_SUCCESS The method is successful.
279 * @exception E_INVALID_ARG Either of the following conditions has occurred:
280 * - A specified input parameter is invalid.
281 * - The comparer has failed to compare the keys.
282 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
283 * @remarks The specific error code can be accessed using the GetLastResult() method.
286 virtual IEnumerator* GetValuesN(const Object& key) const;
289 * Gets a list of all the unique keys in this map.
293 * @return The list of all the unique keys in this map
295 * - The IList stores just the pointers to the elements in the map and not the elements themselves.
296 * - The specific error code can be accessed using the GetLastResult() method.
299 virtual IList* GetKeysN(void) const;
302 * Gets the list of all the values in this map.
306 * @return The list of all the values in this map
308 * - The IList stores just the pointers to the elements in the map and not the elements themselves.
309 * - The specific error code can be accessed using the GetLastResult() method.
312 virtual IList* GetValuesN(void) const;
315 * Removes all the values with the specified key.
319 * @return An error code
320 * @param[in] key The key to remove
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG Either of the following conditions has occurred:
323 * - The specified input parameter is invalid.
324 * - The comparer has failed to compare the keys.
325 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
328 virtual result Remove(const Object& key);
331 * Removes the specified value associated with the specified key.
335 * @return An error code
336 * @param[in] key The key whose mapping is removed from the map
337 * @param[in] value The value to remove
338 * @exception E_SUCCESS The method is successful.
339 * @exception E_INVALID_ARG Either of the following conditions has occurred:
340 * - A specified input parameter is invalid.
341 * - The comparer has failed to compare the keys.
342 * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair has not been found in the map.
343 * @remarks The specified key is also removed if there are no more values associated with it.
346 virtual result Remove(const Object& key, const Object& value);
349 * Removes all the object pointers in the collection. @n
353 * @remarks This method can be called before deleting the collection.
355 virtual void RemoveAll(void);
358 * Sets the value associated with the given key to a new value.
362 * @return An error code
363 * @param[in] key The key for which the associated value is replaced
364 * @param[in] value The value to replace
365 * @param[in] pNewValue A pointer to the new value that replaces the existing value
366 * @exception E_SUCCESS The method is successful.
367 * @exception E_INVALID_ARG Either of the following conditions has occurred:
368 * - A specified input parameter is invalid.
369 * - The comparer has failed to compare the keys.
370 * @exception E_OBJ_NOT_FOUND The specified @c key and @c value pair has not been found in the map.
371 * @remarks To add a new key-value pair, use the Add() method.
375 virtual result SetValue(const Object& key, const Object& value, Object* pNewValue);
378 * Gets the number of values currently stored in this map.
382 * @return The number of values currently stored in this map
384 virtual int GetCount(void) const;
387 * Gets the number of values whose key matches the given key.
391 * @return An error code
392 * @param[in] key A key to locate
393 * @param[out] count The number of values whose key matches the given key
394 * @exception E_SUCCESS The method is successful.
395 * @exception E_INVALID_ARG Either of the following conditions has occurred:
396 * - A specified input parameter is invalid.
397 * - The comparer has failed to compare the keys.
398 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
400 virtual result GetCount(const Object& key, int& count) const;
403 * Checks whether the map contains the specified key and value pair.
407 * @return @c true if the map contains the specified key and value pair, @n
409 * @param[in] key The key to locate
410 * @param[in] value The value to locate
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_INVALID_ARG Either of the following conditions has occurred:
413 * - A specified input parameter is invalid.
414 * - The comparer has failed to compare the keys.
415 * @remarks The specific error code can be accessed using the GetLastResult() method.
417 * @see ContainsValue()
419 virtual bool Contains(const Object& key, const Object& value) const;
422 * Checks whether the map contains the specified key.
426 * @return @c true if the map contains the specified key, @n
428 * @param[in] key The key to locate
429 * @exception E_SUCCESS The method is successful.
430 * @exception E_INVALID_ARG Either of the following conditions has occurred:
431 * - A specified input parameter is invalid.
432 * - The comparer has failed to compare the keys.
433 * @remarks The specific error code can be accessed using the GetLastResult() method.
434 * @see ContainsValue()
437 virtual bool ContainsKey(const Object& key) const;
440 * Checks whether the map contains the specified value.
444 * @return @c true if the map contains the specified value, @n
446 * @param[in] value The value to locate
451 virtual bool ContainsValue(const Object& value) const;
454 * Compares the specified instance to the current instance for equality.
458 * @return @c true if the two instances are equal, @n
460 * @param[in] obj The object to compare with the current instance
461 * @remarks This method returns @c true only if the specified object is also an instance of the %MultiHashMap class,
462 * both the maps have the same number of elements, and both the maps contain the same elements.
464 virtual bool Equals(const Object& obj) const;
467 * Gets the hash value of the current instance.
471 * @return The hash value of the current instance
472 * @remarks The two Tizen::Base::Object::Equals() instances must return the same hash value. @n
473 * For better performance, the used hash function must generate a random distribution for all the inputs.
475 virtual int GetHashCode(void) const;
478 * Gets the element deleter of the collection.
482 * @return A function pointer to the existing element deleter
484 virtual DeleterFunctionType GetDeleter(void) const;
488 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
490 * @param[in] map An instance of %MultiHashMap to initialize the current instance
492 MultiHashMap(const MultiHashMap& map);
495 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
497 * @param[in] map An instance of %MultiHashMap
499 MultiHashMap& operator =(const MultiHashMap& map);
502 * Copies all the pairs from the specified map to this map.
504 * @return An error code
505 * @param[in] map The map to copy
506 * @exception E_SUCCESS The method is successful.
507 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
508 * The @c map is modified during the operation of this method.
510 result AddAll(const IMultiMap& map);
513 * Gets a hash value for the specified object.
515 * @return An @c int hash value for the specified object
516 * @param[in] obj The object to get hash value
518 int Hash(const Object& obj) const;
521 * Rehashes the contents of this map into a new array with a
522 * larger capacity. @n
523 * This method is called automatically when the number of keys in this map reaches its threshold.
525 * @return An error code
526 * @param[in] newCapacity The new capacity @n
527 * It must be a power of two and be greater than current capacity.
528 * @exception E_SUCCESS The method is successful.
530 result Resize(int newCapacity);
533 * Clears all key-value pairs in this map.
538 * Sets the element deleter of the collection.
542 * @param[in] deleter A function pointer to the element deleter to set
544 virtual void SetDeleter(DeleterFunctionType deleter);
546 _MultiHashMapEntry** __pTable;
551 IHashCodeProvider* __pProvider;
552 IComparer* __pComparer;
553 bool __needToRemoveProviderComparer;
555 DeleterFunctionType __deleter;
556 static const int DEFAULT_CAPACITY = 16;
557 static const float DEFAULT_LOAD_FACTOR;
559 friend class _MultiHashMapEnumerator;
560 friend class _MultiHashMapImpl;
561 class _MultiHashMapImpl* __pMultiHashMapImpl;
565 }}} // Tizen::Base::Collection
567 #endif //_FBASE_COL_MULTI_HASH_MAP_H_