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