Sync with tizen_2.2
[platform/framework/native/appfw.git] / inc / FBaseColMultiHashMap.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
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
7 //
8 // http://www.apache.org/licenses/LICENSE-2.0
9 //
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.
15 //
16
17 /**
18  * @file                FBaseColMultiHashMap.h
19  * @brief               This is the header file for the %MultiHashMap class.
20  *
21  * This header file contains the declarations of the %MultiHashMap class.
22  */
23 #ifndef _FBASE_COL_MULTI_HASH_MAP_H_
24 #define _FBASE_COL_MULTI_HASH_MAP_H_
25
26 #include <FBaseObject.h>
27 #include <FBaseColIComparer.h>
28 #include <FBaseColIHashCodeProvider.h>
29 #include <FBaseColIMultiMap.h>
30
31 namespace Tizen { namespace Base { namespace Collection
32 {
33
34 class _MultiHashMapEntry;
35
36 /**
37  * @class MultiHashMap
38  * @brief This class represents a collection of associated keys and values that are organized based on the hash code of the key.
39  *
40  * @since 2.0
41  *
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 with the same key, but duplicated elements with the same key are not allowed.
44  * The key and value cannot be @c null.
45  * @n
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>.
47  *
48  * The following example demonstrates how to use the %MultiHashMap class.
49  *
50  * @code
51  *      #include <FBase.h>
52  *
53  *      using namespace Tizen::Base;
54  *      using namespace Tizen::Base::Collection;
55  *
56  *      void
57  *      MyClass::MultiHashMapSample(void)
58  *      {
59  *              MultiHashMap map(SingleObjectDeleter);
60  *
61  *              // Constructs a MultiHashMap instance with default values for capacity, load factor, hash code provider, and comparer
62  *              map.Construct();
63  *
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)
68  *
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)
73  *              {
74  *                      pValue = static_cast< Integer* > (pValueEnum->GetCurrent());
75  *              }
76  *
77  *              delete pValueEnum;
78  *
79  *              // Removes values with the specified key     // String(L"Two"), Integer(2), Integer(20) are removed
80  *              map.Remove(String(L"Two"));
81  *
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)
86  *              {
87  *                      pKey = static_cast< String* > (pMapEnum->GetKey());
88  *                      pValue = static_cast< Integer* > (pMapEnum->GetValue());
89  *              }
90  *
91  *              delete pMapEnum;
92  *
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.
95  *              // map.RemoveAll();
96  *      }
97  * @endcode
98  */
99 class _OSP_EXPORT_ MultiHashMap
100         : public IMultiMap
101         , public Object
102 {
103 public:
104         using IMultiMap::Add;
105         using IMultiMap::Remove;
106         using IMultiMap::RemoveAll;
107         using IMultiMap::SetValue;
108         using IMultiMap::Contains;
109         using IMultiMap::ContainsKey;
110
111         /**
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.
114          *
115          * @since 2.0
116          *
117          * @param[in]   deleter The function pointer to type of the element deleter
118          * @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
119          *                      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.
120          *                      It means that you do not transfer the ownership of elements to the collection.
121          * @see         NoOpDeleter()
122          * @see         SingleObjectDeleter()
123          * @see         ArrayDeleter()
124          */
125         explicit MultiHashMap(DeleterFunctionType deleter = NoOpDeleter);
126
127         /**
128          * This destructor overrides Tizen::Base::Object::~Object().
129          *
130          * @since 2.0
131          */
132         virtual ~MultiHashMap(void);
133
134         /**
135          * Initializes a new instance of %MultiHashMap with the specified capacity and load factor.
136          *
137          * @since 2.0
138          *
139          * @return              An error code
140          * @param[in]   capacity                The initial capacity
141          * @param[in]   loadFactor              The maximum ratio of elements to buckets
142          * @exception   E_SUCCESS               The method is successful.
143          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
144          *                                                              the @c capacity or the @c loadFactor is negative.
145          * @remarks             The GetHashCode() method of the key object is used for hashing and the
146          *                              Equals() method of the key object is used for comparing the keys.
147          * @see                 MultiHashMap()
148          */
149         result Construct(int capacity = 16, float loadFactor = 0.75);
150
151         /**
152          * Initializes a new instance of %MultiHashMap by copying the elements of the given map.
153          *
154          * @since 2.0
155          *
156          * @return              An error code
157          * @param[in]   map                             The map to copy
158          * @param[in]   loadFactor              The maximum ratio of elements to buckets @n
159          *                                                              If it is @c 0, the default load factor(0.75) is used.
160          * @exception   E_SUCCESS                       The method is successful.
161          * @exception   E_INVALID_ARG           The specified @c loadFactor is negative.
162          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
163          *                                                                      the @c map is modified during the operation of this method.
164          * @remarks             This method performs a shallow copy. It copies just the pointer; not the element itself.
165          * @see                 MultiHashMap()
166          */
167         result Construct(const IMultiMap& map, float loadFactor = 0.75);
168
169
170         /**
171          * Initializes a new instance of the %MultiHashMap class, with the specified initial capacity, load factor, hash code provider, and comparer.
172          *
173          * @since 2.0
174          *
175          * @return              An error code
176          * @param[in]   capacity        The initial capacity @n
177          *                                                      If it is @c 0, the default capacity (16) is used.
178          * @param[in]   loadFactor      The maximum ratio of elements to buckets @n
179          *                                                      If it is @c 0, the default load factor (0.75) is used.
180          * @param[in]   provider        An instance of the IHashCodeProvider derived class that supplies the hash codes
181          *                                                      for all keys in this map
182          * @param[in]   comparer        An instance of the IComparer derived class to use when comparing keys
183          * @exception   E_SUCCESS               The method is successful.
184          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
185          *                                                              the @c capacity or the @c loadFactor is negative.
186          * @remarks             The instances of hash code provider and comparer will not be deallocated later from this map.
187          * @see                 MultiHashMap()
188          */
189         result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
190
191         /**
192          * Initializes a new instance of the %MultiHashMap class by copying the elements of the specified map,
193          * with the specified load factor, hash code provider, and comparer.
194          *
195          * @since 2.0
196          *
197          * @return              An error code
198          * @param[in]   map                     A map to copy
199          * @param[in]   loadFactor      The maximum ratio of elements to buckets @n
200          *                                                      If it is @c 0, the default load factor (0.75) is used.
201          * @param[in]   provider        An instance of the IHashCodeProvider derived class that supplies the hash codes
202          *                                                      for all keys in this map
203          * @param[in]   comparer        An instance of the IComparer derived class to use when comparing keys
204          * @exception   E_SUCCESS                       The method is successful.
205          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
206          *                                                                      the @c loadFactor is negative.
207          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
208          *                                                                      the @c map is modified during the operation of this method.
209          * @remarks             This method performs a shallow copy. It copies just the pointer; not the element itself.
210          *                      The instances of hash code provider and comparer will not be deallocated later from this map.
211          * @see                 MultiHashMap()
212          */
213         result Construct(const IMultiMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
214
215         /**
216          * Adds the specified key-value pair to this map.
217          *
218          * @since 2.0
219          *
220          * @return              An error code
221          * @param[in]   pKey    The pointer to key to add
222          * @param[in]   pValue  The pointer to corresponding value to add
223          * @exception   E_SUCCESS                       The method is successful.
224          * @exception   E_OBJ_ALREADY_EXIST     The specified pair of @c pKey and @c pValue already exists.
225          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
226          *                                                                      the comparer has failed to compare the keys.
227          * @remarks             This method performs a shallow copy. It adds just the pointer; not the element itself.
228          * @see                 Remove()
229          */
230         virtual result Add(Object* pKey, Object* pValue);
231
232         /**
233          * Gets an enumerator of this map.
234          *
235          * @since 2.0
236          *
237          * @return              An enumerator (an instance of the IEnumerator derived class) of this map, @n
238          *                              else @c null if some exception occurs
239          * @remarks             If the key has multiple values, the enumeration proceeds as follows: {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
240          *                              The specific error code can be accessed using the GetLastResult() method.
241          * @see                 IMapEnumerator
242          */
243         virtual IEnumerator* GetEnumeratorN(void) const;
244
245         /**
246          * Gets an enumerator of this map.
247          *
248          * @since 2.0
249          *
250          * @return              An enumerator (an instance of the IMapEnumerator derived class) of this map, @n
251          *                              else @c null if some exception occurs
252          * @remarks             If the key has multiple values, the enumeration proceeds as follows: {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
253          *                      The specific error code can be accessed using the GetLastResult() method.
254          * @see                 IEnumerator
255          */
256         virtual IMapEnumerator* GetMapEnumeratorN(void) const;
257
258         /**
259          * Gets an enumerator of the values associated with the specified key.
260          *
261          * @since 2.0
262          *
263          * @return              An enumerator (an instance of the IEnumerator derived class) of the values associated with the specified key, @n
264          *                              else @c null if some exception occurs
265          * @param[in]   key                             A key to locate
266          * @exception   E_SUCCESS                       The method is successful.
267          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
268          *                                                                      the comparer has failed to compare the keys.
269          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
270          * @remarks             The specific error code can be accessed using the GetLastResult() method.
271          * @see                 SetValue()
272          */
273         virtual IEnumerator* GetValuesN(const Object& key) const;
274
275         /**
276          * Gets a list of all unique keys in this map.
277          *
278          * @since 2.0
279          *
280          * @return              A list of all unique keys in this map
281          * @remarks             The %IList stores just the pointers to the elements in the map, not the elements themselves.
282          *                              The specific error code can be accessed using the GetLastResult() method.
283          * @see                 GetValuesN()
284          */
285         virtual IList* GetKeysN(void) const;
286
287         /**
288          * Gets a list of all the values in this map.
289          *
290          * @since 2.0
291          *
292          * @return              A list of all the values in this map
293          * @remarks             The IList stores just the pointers to the elements in the map, not the elements themselves.
294          *                              The specific error code can be accessed using the GetLastResult() method.
295          * @see                 GetKeysN()
296          */
297         virtual IList* GetValuesN(void) const;
298
299         /**
300          * Removes all the values with the specified key.
301          *
302          * @since 2.0
303          *
304          * @return              An error code
305          * @param[in]   key                                     The key to remove
306          * @exception   E_SUCCESS                       The method is successful.
307          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
308          *                                                                      the comparer has failed to compare keys.
309          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
310          * @see                 Add()
311          */
312         virtual result Remove(const Object& key);
313
314         /**
315          * Removes the specified value associated with the specified key.
316          *
317          * @since 2.0
318          *
319          * @return              An error code
320          * @param[in]   key             The key whose mapping is to remove from the map
321          * @param[in]   value   The value to remove
322          * @exception   E_SUCCESS                       The method is successful.
323          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
324          *                                                                      the comparer has failed to compare the keys.
325          * @exception   E_OBJ_NOT_FOUND         The specified @c key and @c value pair is not found in the map.
326          * @remarks             The specified key is also removed if there are no more values associated with it.
327          * @see                 Add()
328          */
329         virtual result Remove(const Object& key, const Object& value);
330
331         /**
332          * Removes all the object pointers in the @c collection. @n
333          *
334          * @since 2.0
335          *
336          * @remarks             This method can be called before deleting @c collection.
337          */
338         virtual void RemoveAll(void);
339
340         /**
341          * Sets the value associated with the given key with a new value.
342          *
343          * @since 2.0
344          *
345          * @return              An error code
346          * @param[in]   key                     The key for which the associated value needs to replace
347          * @param[in]   value           The value to replace
348          * @param[in]   pNewValue       The pointer to new value to replace the existing value
349          * @exception   E_SUCCESS                       The method is successful.
350          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
351          *                                                                      the comparer has failed to compare the keys.
352          * @exception   E_OBJ_NOT_FOUND         The specified @c key and @c value pair is not found in the map.
353          * @remarks             To add a new key-value pair, use the Add() method.
354          * @see                 Add()
355          * @see                 GetValuesN()
356          */
357         virtual result SetValue(const Object& key, const Object& value, Object* pNewValue);
358
359         /**
360          * Gets the number of values currently stored in this map.
361          *
362          * @since 2.0
363          *
364          * @return              The number of values currently stored in this map
365          */
366         virtual int GetCount(void) const;
367
368         /**
369          * Gets the number of values whose key matches the key.
370          *
371          * @since 2.0
372          *
373          * @return              An error code
374          * @param[in]   key     A key to locate
375          * @param[out]  count   The number of values whose key is the @c key
376          * @exception   E_SUCCESS                       The method is successful.
377          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
378          *                                                                      the comparer has failed to compare the keys.
379          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
380          */
381         virtual result GetCount(const Object& key, int& count) const;
382
383         /**
384          * Checks whether the map contains the specified key and value.
385          *
386          * @since 2.0
387          *
388          * @return              @c true if the map contains the specified key and value pair, @n
389          *                              else @c false
390          * @param[in]   key             The key to locate
391          * @param[in]   value   The value to locate
392          * @exception   E_SUCCESS               The method is successful.
393          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
394          *                                                              the comparer has failed to compare the keys.
395          * @remarks             The specific error code can be accessed using the GetLastResult() method.
396          * @see                 ContainsKey()
397          * @see                 ContainsValue()
398          */
399         virtual bool Contains(const Object& key, const Object& value) const;
400
401         /**
402          * Checks whether the map contains the specified key.
403          *
404          * @since 2.0
405          *
406          * @return              @c true if the map contains the specified key, @n
407          *                              else @c false
408          * @param[in]   key                     The key to locate
409          * @exception   E_SUCCESS               The method is successful.
410          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
411          *                                                              the comparer has failed to compare the keys.
412          * @remarks             The specific error code can be accessed using the GetLastResult() method.
413          * @see                 ContainsValue()
414          * @see                 Contains()
415          */
416         virtual bool ContainsKey(const Object& key) const;
417
418         /**
419          * Checks whether the map contains the specified value.
420          *
421          * @since 2.0
422          *
423          * @return              @c true if the map contains the specified value, @n
424          *                              else @c false
425          * @param[in]   value   The value to locate
426          *
427          * @see                         ContainsKey()
428          * @see                         Contains()
429          */
430         virtual bool ContainsValue(const Object& value) const;
431
432         /**
433          * Compares the specified instance to the current instance for equality.
434          *
435          * @since 2.0
436          *
437          * @return              @c true if the two instances are equal, @n
438          *                              @c false
439          * @param[in]   obj The object to compare with the current instance
440          * @remarks             This method returns @c true only if the specified object is also an instance of %MultiHashMap class,
441          *                              both maps have the same number of elements, and both maps contain the same elements.
442          */
443         virtual bool Equals(const Object& obj) const;
444
445         /**
446          * Gets the hash value of the current instance.
447          *
448          * @since 2.0
449          *
450          * @return      The hash value of the current instance
451          * @remarks     The two Tizen::Base::Object::Equals() instances must return the same hash value. For better performance, @n
452          *                      the used hash function must generate a random distribution for all inputs.
453          */
454         virtual int GetHashCode(void) const;
455
456         /**
457          * Gets the element deleter of the collection.
458          *
459          * @since 2.0
460          *
461          * @return              A function pointer to the existing element deleter
462          */
463         virtual DeleterFunctionType GetDeleter(void) const;
464
465 private:
466         /**
467          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
468          *
469          * @param[in]   map An instance of %MultiHashMap to initialize the current instance
470          */
471         MultiHashMap(const MultiHashMap& map);
472
473         /**
474          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
475          *
476          * @param[in]   map An instance of %MultiHashMap
477          */
478         MultiHashMap& operator =(const MultiHashMap& map);
479
480         /**
481          * Copies all the pairs from the specified map to this map.
482          *
483          * @return              An error code
484          * @param[in]   map                                     The map to copy
485          * @exception   E_SUCCESS                       The method is successful.
486          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
487          *                                                                      The @c map is modified during the operation of this method.
488          */
489         result AddAll(const IMultiMap& map);
490
491         /**
492          * Gets a hash value for the specified object.
493          *
494          * @return              An @c int hash value for the specified object
495          * @param[in]   obj     The object to get hash value
496          */
497         int Hash(const Object& obj) const;
498
499         /**
500          * Rehashes the contents of this map into a new array with a
501          * larger capacity. @n
502          * This method is called automatically when the number of keys in this map reaches its threshold.
503          *
504          * @return              An error code
505          * @param[in]   newCapacity             The new capacity @n
506          *                                                              It must be a power of two and be greater than current capacity.
507          * @exception   E_SUCCESS               The method is successful.
508          */
509         result Resize(int newCapacity);
510
511         /**
512          * Clears all key-value pairs in this map.
513          */
514         void Reset(void);
515
516         /**
517          * Sets the element deleter of the collection.
518          *
519          * @since 2.0
520          *
521          * @param[in]   deleter A function pointer to the element deleter to set
522          */
523         virtual void SetDeleter(DeleterFunctionType deleter);
524
525         _MultiHashMapEntry** __pTable;
526         int __count;
527         int __capacity;
528         float __loadFactor;
529         int __threshold;
530         IHashCodeProvider* __pProvider;
531         IComparer* __pComparer;
532         bool __needToRemoveProviderComparer;
533         int __modCount;
534         DeleterFunctionType __deleter;
535         static const int DEFAULT_CAPACITY = 16;
536         static const float DEFAULT_LOAD_FACTOR;
537
538         friend class _MultiHashMapEnumerator;
539         friend class _MultiHashMapImpl;
540         class _MultiHashMapImpl* __pMultiHashMapImpl;
541
542 }; // MultiHashMap
543
544 }}} // Tizen::Base::Collection
545
546 #endif //_FBASE_COL_MULTI_HASH_MAP_H_