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 having the same key, but duplicate elements with the same key are not allowed.
  44  * The key and value cannot be a @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                 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.
 122          * @see         NoOpDeleter()
 123          * @see         SingleObjectDeleter()
 124          * @see         ArrayDeleter()
 125          */
 126         explicit MultiHashMap(DeleterFunctionType deleter = NoOpDeleter);
 127
 128         /**
 129          * This destructor overrides Tizen::Base::Object::~Object().
 130          *
 131          * @since 2.0
 132          */
 133         virtual ~MultiHashMap(void);
 134
 135         /**
 136          * Initializes a new instance of %MultiHashMap with the specified @c capacity and @c loadFactor.
 137          *
 138          * @since 2.0
 139          *
 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()
 150          */
 151         result Construct(int capacity = 16, float loadFactor = 0.75);
 152
 153         /**
 154          * Initializes a new instance of %MultiHashMap by copying the elements of the given @c map.
 155          *
 156          * @since 2.0
 157          *
 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()
 169          */
 170         result Construct(const IMultiMap& map, float loadFactor = 0.75);
 171
 172
 173         /**
 174          * Initializes a new instance of the %MultiHashMap class, with the specified initial capacity, load factor, hash code provider, and comparer.
 175          *
 176          * @since 2.0
 177          *
 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()
 192          */
 193         result Construct(int capacity, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
 194
 195         /**
 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.
 198          *
 199          * @since 2.0
 200          *
 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.
 215          * @remarks
 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()
 219          */
 220         result Construct(const IMultiMap& map, float loadFactor, const IHashCodeProvider& provider, const IComparer& comparer);
 221
 222         /**
 223          * Adds the specified key-value pair to this map.
 224          *
 225          * @since 2.0
 226          *
 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.
 236          * @see                 Remove()
 237          */
 238         virtual result Add(Object* pKey, Object* pValue);
 239
 240         /**
 241          * Gets the enumerator of this map.
 242          *
 243          * @since 2.0
 244          *
 245          * @return              The enumerator (an instance of the IEnumerator derived class) of this map, @n
 246          *                              else @c null if an exception occurs
 247          * @remarks
 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
 252          */
 253         virtual IEnumerator* GetEnumeratorN(void) const;
 254
 255         /**
 256          * Gets the enumerator of this map.
 257          *
 258          * @since 2.0
 259          *
 260          * @return              The enumerator (an instance of the IMapEnumerator derived class) of this map, @n
 261          *                              else @c null if an exception occurs
 262          * @remarks
 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.
 266          * @see                 IEnumerator
 267          */
 268         virtual IMapEnumerator* GetMapEnumeratorN(void) const;
 269
 270         /**
 271          * Gets the enumerator of the values associated with the specified key.
 272          *
 273          * @since 2.0
 274          *
 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.
 284          * @see                 SetValue()
 285          */
 286         virtual IEnumerator* GetValuesN(const Object& key) const;
 287
 288         /**
 289          * Gets a list of all the unique keys in this map.
 290          *
 291          * @since 2.0
 292          *
 293          * @return              The list of all the unique keys in this map
 294          * @remarks
 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.
 297          * @see                 GetValuesN()
 298          */
 299         virtual IList* GetKeysN(void) const;
 300
 301         /**
 302          * Gets the list of all the values in this map.
 303          *
 304          * @since 2.0
 305          *
 306          * @return              The list of all the values in this map
 307          * @remarks
 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.
 310          * @see                 GetKeysN()
 311          */
 312         virtual IList* GetValuesN(void) const;
 313
 314         /**
 315          * Removes all the values with the specified key.
 316          *
 317          * @since 2.0
 318          *
 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.
 326          * @see                 Add()
 327          */
 328         virtual result Remove(const Object& key);
 329
 330         /**
 331          * Removes the specified value associated with the specified key.
 332          *
 333          * @since 2.0
 334          *
 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.
 344          * @see                 Add()
 345          */
 346         virtual result Remove(const Object& key, const Object& value);
 347
 348         /**
 349          * Removes all the object pointers in the collection. @n
 350          *
 351          * @since 2.0
 352          *
 353          * @remarks             This method can be called before deleting the collection.
 354          */
 355         virtual void RemoveAll(void);
 356
 357         /**
 358          * Sets the value associated with the given key to a new value.
 359          *
 360          * @since 2.0
 361          *
 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.
 372          * @see                 Add()
 373          * @see                 GetValuesN()
 374          */
 375         virtual result SetValue(const Object& key, const Object& value, Object* pNewValue);
 376
 377         /**
 378          * Gets the number of values currently stored in this map.
 379          *
 380          * @since 2.0
 381          *
 382          * @return              The number of values currently stored in this map
 383          */
 384         virtual int GetCount(void) const;
 385
 386         /**
 387          * Gets the number of values whose key matches the given key.
 388          *
 389          * @since 2.0
 390          *
 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.
 399          */
 400         virtual result GetCount(const Object& key, int& count) const;
 401
 402         /**
 403          * Checks whether the map contains the specified key and value pair.
 404          *
 405          * @since 2.0
 406          *
 407          * @return              @c true if the map contains the specified key and value pair, @n
 408          *                              else @c false
 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.
 416          * @see                 ContainsKey()
 417          * @see                 ContainsValue()
 418          */
 419         virtual bool Contains(const Object& key, const Object& value) const;
 420
 421         /**
 422          * Checks whether the map contains the specified key.
 423          *
 424          * @since 2.0
 425          *
 426          * @return              @c true if the map contains the specified key, @n
 427          *                              else @c false
 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()
 435          * @see                 Contains()
 436          */
 437         virtual bool ContainsKey(const Object& key) const;
 438
 439         /**
 440          * Checks whether the map contains the specified value.
 441          *
 442          * @since 2.0
 443          *
 444          * @return              @c true if the map contains the specified value, @n
 445          *                              else @c false
 446          * @param[in]   value   The value to locate
 447          *
 448          * @see                         ContainsKey()
 449          * @see                         Contains()
 450          */
 451         virtual bool ContainsValue(const Object& value) const;
 452
 453         /**
 454          * Compares the specified instance to the current instance for equality.
 455          *
 456          * @since 2.0
 457          *
 458          * @return              @c true if the two instances are equal, @n
 459          *                              @c false
 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.
 463          */
 464         virtual bool Equals(const Object& obj) const;
 465
 466         /**
 467          * Gets the hash value of the current instance.
 468          *
 469          * @since 2.0
 470          *
 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.
 474          */
 475         virtual int GetHashCode(void) const;
 476
 477         /**
 478          * Gets the element deleter of the collection.
 479          *
 480          * @since 2.0
 481          *
 482          * @return              A function pointer to the existing element deleter
 483          */
 484         virtual DeleterFunctionType GetDeleter(void) const;
 485
 486 private:
 487         /**
 488          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 489          *
 490          * @param[in]   map An instance of %MultiHashMap to initialize the current instance
 491          */
 492         MultiHashMap(const MultiHashMap& map);
 493
 494         /**
 495          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 496          *
 497          * @param[in]   map An instance of %MultiHashMap
 498          */
 499         MultiHashMap& operator =(const MultiHashMap& map);
 500
 501         /**
 502          * Copies all the pairs from the specified map to this map.
 503          *
 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.
 509          */
 510         result AddAll(const IMultiMap& map);
 511
 512         /**
 513          * Gets a hash value for the specified object.
 514          *
 515          * @return              An @c int hash value for the specified object
 516          * @param[in]   obj     The object to get hash value
 517          */
 518         int Hash(const Object& obj) const;
 519
 520         /**
 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.
 524          *
 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.
 529          */
 530         result Resize(int newCapacity);
 531
 532         /**
 533          * Clears all key-value pairs in this map.
 534          */
 535         void Reset(void);
 536
 537         /**
 538          * Sets the element deleter of the collection.
 539          *
 540          * @since 2.0
 541          *
 542          * @param[in]   deleter A function pointer to the element deleter to set
 543          */
 544         virtual void SetDeleter(DeleterFunctionType deleter);
 545
 546         _MultiHashMapEntry** __pTable;
 547         int __count;
 548         int __capacity;
 549         float __loadFactor;
 550         int __threshold;
 551         IHashCodeProvider* __pProvider;
 552         IComparer* __pComparer;
 553         bool __needToRemoveProviderComparer;
 554         int __modCount;
 555         DeleterFunctionType __deleter;
 556         static const int DEFAULT_CAPACITY = 16;
 557         static const float DEFAULT_LOAD_FACTOR;
 558
 559         friend class _MultiHashMapEnumerator;
 560         friend class _MultiHashMapImpl;
 561         class _MultiHashMapImpl* __pMultiHashMapImpl;
 562
 563 }; // MultiHashMap
 564
 565 }}} // Tizen::Base::Collection
 566
 567 #endif //_FBASE_COL_MULTI_HASH_MAP_H_