inc/FBaseColIMap.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                FBaseColIMap.h
  19  * @brief               This is the header file for the %IMap interface.
  20  *
  21  * This header file contains the declarations of the %IMap interface.
  22  */
  23 #ifndef _FBASE_COL_IMAP_H_
  24 #define _FBASE_COL_IMAP_H_
  25
  26 #include <FBaseColICollection.h>
  27 #include <FBaseColTypes.h>
  28 #include <FBaseColIMapEnumerator.h>
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace Base { namespace Collection
  32 {
  33
  34 class IList;
  35 class MapEntry;
  36
  37 /**
  38  * @interface   IMap
  39  * @brief               This interface represents a collection of key-value pairs.
  40  *
  41  * @since 2.0
  42  *
  43  * The %IMap interface represents a collection of key-value pairs. An %IMap instance
  44  * contains unique keys and each key maps to a single value.
  45  * The key and value cannot be a @c null reference.
  46  *
  47  * 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  */
  49 class _OSP_EXPORT_ IMap
  50         : public virtual ICollection
  51 {
  52 public:
  53         /**
  54          * This polymorphic destructor should be overridden if required. @n
  55          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  56          *
  57          * @since 2.0
  58          */
  59         virtual ~IMap(void) {}
  60
  61         /**
  62          * @if OSPDEPREC
  63          * Adds the specified key-value pair to the map.
  64          *
  65          * @brief               <i> [Deprecated] </i>
  66          * @deprecated  This method is deprecated because it has a problem of constant reference argument.
  67          *                              Instead of using this method, use Add(Object* pKey, Object* pValue).
  68          * @since 2.0
  69          *
  70          * @return              An error code
  71          * @param[in]   key                             The key to add
  72          * @param[in]   value                           The corresponding value to add
  73          * @exception   E_SUCCESS                       The method is successful.
  74          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
  75          *                                                                      - A specified input parameter is invalid.
  76          *                                                                      - The comparer has failed to compare the keys.
  77          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key already exists.
  78          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
  79          * @see Remove()
  80          * @endif
  81          */
  82         result Add(const Object& key, const Object& value)
  83         {
  84                 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
  85         }
  86
  87         /**
  88          * Adds the specified key-value pair to the map.
  89          *
  90          * @since 2.0
  91          *
  92          * @return              An error code
  93          * @param[in]   pKey                            A pointer to the key to add
  94          * @param[in]   pValue                          A pointer to the corresponding value to add
  95          * @exception   E_SUCCESS                       The method is successful.
  96          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
  97          *                                                                      - A specified input parameter is invalid.
  98          *                                                                      - The comparer has failed to compare the keys.
  99          * @exception   E_OBJ_ALREADY_EXIST     The specified @c pKey already exists.
 100          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
 101          * @see Remove()
 102          */
 103         virtual result Add(Object* pKey, Object* pValue) = 0;
 104
 105         /**
 106          * Checks whether the key exists. If the key does not exist, the Add() method is called. Unless, the SetValue() method is called.
 107          *
 108          * @since 2.0
 109          *
 110          * @return              An error code
 111          * @param[in]   pKey                            A pointer to the key to add
 112          * @param[in]   pValue                          A pointer to the corresponding value to add
 113          * @exception   E_SUCCESS                       The method is successful.
 114          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 115          *                                                                      - A specified input parameter is invalid.
 116          *                                                                      - The comparer has failed to compare the keys.
 117          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
 118          * @see                 Add(Object*, Object*)
 119          * @see                 SetValue()
 120          */
 121         result AddIfNotExistOrSet(Object* pKey, Object* pValue)
 122         {
 123                 if (!ContainsKey(*pKey))
 124                 {
 125                         return Add(pKey, pValue);
 126                 }
 127                 else
 128                 {
 129                         return SetValue(*pKey, pValue);
 130                 }
 131         }
 132
 133         /**
 134          * Gets the value associated to the specified @c key.
 135          *
 136          * @since 2.0
 137          *
 138          * @return              The value associated to the specified key, @n
 139          *                              else @c null if an exception occurs
 140          * @param[in]   key                             The key used to find the associated value
 141          * @exception   E_SUCCESS               The method is successful.
 142          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 143          *                                                              - The specified input parameter is invalid.
 144          *                                                              - The comparer has failed to compare the keys.
 145          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 146          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 147          * @see                 SetValue()
 148          */
 149         virtual const Object* GetValue(const Object& key) const = 0;
 150
 151         /**
 152          * Gets the value associated to the specified @c key.
 153          *
 154          * @since 2.0
 155          *
 156          * @return              The value associated to the specified key, @n
 157          *                              else @c null if an exception occurs
 158          * @param[in]   key                             The key used to find the associated value
 159          * @exception   E_SUCCESS               The method is successful.
 160          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 161          *                                                              - The specified input parameter is invalid.
 162          *                                                              - The comparer has failed to compare the keys.
 163          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 164          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 165          * @see                 SetValue()
 166          */
 167         virtual Object* GetValue(const Object& key) = 0;
 168
 169         /**
 170          * Gets a list of all the keys in the map.
 171          *
 172          * @since 2.0
 173          *
 174          * @return              A pointer to the list of all the keys in the map, @n
 175          *                              else @c null if an exception occurs
 176          * @remarks
 177          *                              - The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
 178          *                              - The %IList interface stores just the pointers to the elements in the map and not the elements themselves.
 179          *                              - The specific error code can be accessed using the GetLastResult() method.
 180          */
 181         virtual IList* GetKeysN(void) const = 0;
 182
 183         /**
 184          * Gets the list of all the values in the map.
 185          *
 186          * @since 2.0
 187          *
 188          * @return              A pointer to the list of all the values in the map, @n
 189          *                              else @c null if an exception occurs
 190          * @remarks
 191          *                              - The IList interface stores just the pointers to the elements in the map and not the elements themselves.
 192          *                              - The specific error code can be accessed using the GetLastResult() method.
 193          * @see                 GetKeysN()
 194          */
 195         virtual IList* GetValuesN(void) const = 0;
 196
 197         /**
 198          * Removes the value associated to the specified @c key.
 199          *
 200          * @since 2.0
 201          *
 202          * @return              An error code
 203          * @param[in]   key                     The key to remove
 204          * @param[in]   forceDeletion   Set to @c true to deallocate the object, @n
 205          *                                                              else @c false
 206          * @exception   E_SUCCESS               The method is successful.
 207          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 208          *                                                              - A specified input parameter is invalid.
 209          *                                                              - The comparer has failed to compare the keys.
 210          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 211          * @remarks
 212          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 213          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 214          *                              If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
 215          *                              - Remove(key, @b true) internally works as the below code:
 216          * @code
 217          * DeleterFunctionType deleter = GetDeleter();
 218          * SetDeleter(SingleObjectDeleter);
 219          * Remove(key);
 220          * SetDeleter(deleter);
 221          * @endcode
 222          *                              - Remove(key, @b false) internally works as the below code:
 223          * @code
 224          * DeleterFunctionType deleter = GetDeleter();
 225          * SetDeleter(NoOpDeleter);
 226          * Remove(key);
 227          * SetDeleter(deleter);
 228          * @endcode
 229          * @see                 Add(Object*, Object*)
 230          */
 231         result Remove(const Object& key, bool forceDeletion)
 232         {
 233                 DeleterFunctionType deleter = GetDeleter();
 234
 235                 if (forceDeletion)
 236                 {
 237                         SetDeleter(SingleObjectDeleter);
 238                 }
 239                 else
 240                 {
 241                         SetDeleter(NoOpDeleter);
 242                 }
 243
 244                 result r = Remove(key);
 245                 SetDeleter(deleter);
 246                 return r;
 247         }
 248
 249         /**
 250          * Removes the value associated to the specified @c key.
 251          *
 252          * @since 2.0
 253          *
 254          * @return              An error code
 255          * @param[in]   key                             The key for which the value is removed
 256          * @exception   E_SUCCESS               The method is successful.
 257          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 258          *                                                              - The specified input parameter is invalid.
 259          *                                                              - The comparer has failed to compare the keys.
 260          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 261          * @see                 Add(Object*, Object*)
 262          */
 263         virtual result Remove(const Object& key) = 0;
 264
 265         /**
 266          * Removes all the object pointers in the collection. @n
 267          * If @c forceDeletion is set to @c true, the method also removes all the objects. The %RemoveAll() method can be called before deleting the collection.
 268          *
 269          * @since 2.0
 270          *
 271          * @param[in]   forceDeletion           Set to @c true to deallocate all the objects, @n
 272          *                                                                      else @c false
 273          * @remarks
 274          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 275          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 276          *                              If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
 277          *                              - RemoveAll(@b true) internally works as the below code:
 278          * @code
 279          * DeleterFunctionType deleter = GetDeleter();
 280          * SetDeleter(SingleObjectDeleter);
 281          * RemoveAll();
 282          * SetDeleter(deleter);
 283          * @endcode
 284          *                              - RemoveAll(@b false) internally works as the below code:
 285          * @code
 286          * DeleterFunctionType deleter = GetDeleter();
 287          * SetDeleter(NoOpDeleter);
 288          * RemoveAll();
 289          * SetDeleter(deleter);
 290          * @endcode
 291          */
 292         void RemoveAll(bool forceDeletion)
 293         {
 294                 DeleterFunctionType deleter = GetDeleter();
 295
 296                 if (forceDeletion)
 297                 {
 298                         SetDeleter(SingleObjectDeleter);
 299                 }
 300                 else
 301                 {
 302                         SetDeleter(NoOpDeleter);
 303                 }
 304
 305                 RemoveAll();
 306                 SetDeleter(deleter);
 307         }
 308
 309         /**
 310          * Removes all the object pointers from the collection. @n
 311          *
 312          * @since 2.0
 313          */
 314         virtual void RemoveAll(void) = 0;
 315
 316         /**
 317          * Replaces the value associated to the specified @c key with the specified @c value.
 318          *
 319          * @since 2.0
 320          *
 321          * @return              An error code
 322          * @param[in]   key                             The key for which the value is replaced
 323          * @param[in]   value                           The new value
 324          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 325          *                                                                      else @c false
 326          * @exception   E_SUCCESS                       The method is successful.
 327          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 328          *                                                                      - A specified input parameter is invalid.
 329          *                                                                      - The comparer has failed to compare the keys.
 330          * @exception   E_OBJ_NOT_FOUND         The specified @c key has not been found in the map.
 331          * @remarks
 332          *                      - Use the Add(Object*, Object*) method to add a new key-value pair.
 333          *                      - Based on the specified element deleter, the set operation not only gets rid of an element from the list, but also deletes its object instance. @n
 334          *                      The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n
 335          *                      If both the element deleter and the @c forceDeletion are set, the set operation follows the @c forceDeletion setting.
 336          *                      - SetValue(key, value, @b true) internally works as the below code:
 337          * @code
 338          * DeleterFunctionType deleter = GetDeleter();
 339          * SetDeleter(SingleObjectDeleter);
 340          * SetValue(key, const_cast< Object* >(&value));
 341          * SetDeleter(deleter);
 342          * @endcode
 343          *                      - SetValue(key, value, @b false) internally works as the below code:
 344          * @code
 345          * DeleterFunctionType deleter = GetDeleter();
 346          * SetDeleter(NoOpDeleter);
 347          * SetValue(key, const_cast< Object* >(&value));
 348          * SetDeleter(deleter);
 349          * @endcode
 350          * @see         GetValue()
 351          */
 352         result SetValue(const Object& key, const Object& value, bool forceDeletion = false)
 353         {
 354                 DeleterFunctionType deleter = GetDeleter();
 355
 356                 if (forceDeletion)
 357                 {
 358                         SetDeleter(SingleObjectDeleter);
 359                 }
 360                 else
 361                 {
 362                         SetDeleter(NoOpDeleter);
 363                 }
 364
 365                 result r = SetValue(key, const_cast< Object* >(&value));
 366                 SetDeleter(deleter);
 367                 return r;
 368         }
 369
 370         /**
 371          * Replaces the value associated to the specified @c key with the specified @c value.
 372          *
 373          * @since 2.0
 374          *
 375          * @return              An error code
 376          * @param[in]   key                             The key for which the value is replaced
 377          * @param[in]   pValue                  A pointer to the new value
 378          * @exception   E_SUCCESS               The method is successful.
 379          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 380          *                                                              - A specified input parameter is invalid.
 381          *                                                              - The comparer has failed to compare the keys.
 382          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 383          * @remarks             Use the Add(Object*, Object*) method to add a new key-value pair.
 384          * @see                 GetValue()
 385          */
 386         virtual result SetValue(const Object& key, Object* pValue) = 0;
 387
 388         /**
 389          * @if OSPDEPREC
 390          * Checks whether the map contains the specified @c key.
 391          *
 392          * @brief               <i> [Deprecated] </i>
 393          * @deprecated  This method is deprecated because it transfers the result of the comparison in an out-parameter form.
 394          *                              The return type is changed into boolean and this method returns the result.
 395          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 396          * @since 2.0
 397          *
 398          * @return              An error code
 399          * @param[in]   key                     The key to locate
 400          * @param[out]  out                             Set to @c true if the map contains the specified key, @n
 401          *                                                              else @c false
 402          * @exception   E_SUCCESS               The method is successful.
 403          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 404          *                                                              - A specified input parameter is invalid.
 405          *                                                              - The comparer has failed to compare the keys.
 406          * @see                 ContainsValue()
 407          * @endif
 408          */
 409         result ContainsKey(const Object& key, bool& out) const
 410         {
 411                 out = ContainsKey(key);
 412                 result r = GetLastResult();
 413                 return r;
 414         }
 415
 416         /**
 417          * Checks whether the map contains the specified @c key.
 418          *
 419          * @since 2.0
 420          *
 421          * @return              @c true if the map contains the specified key, @n
 422          *                              else @c false
 423          * @param[in]   key                     The key to locate
 424          * @exception   E_SUCCESS               The method is successful.
 425          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 426          *                                                              - The specified input parameter is invalid.
 427          *                                                              - The comparer has failed to compare the keys.
 428          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 429          * @see                 ContainsValue()
 430          */
 431         virtual bool ContainsKey(const Object& key) const = 0;
 432
 433         /**
 434          * Checks whether the map contains the specified @c value.
 435          *
 436          * @since 2.0
 437          *
 438          * @return              @c true if the map contains the specified value, @n
 439          *                              else @c false
 440          * @param[in]   value   The value to locate
 441          *
 442          * @see                 ContainsKey(const Object&)
 443          */
 444         virtual bool ContainsValue(const Object& value) const = 0;
 445
 446         /**
 447         * Gets an instance of IMapEnumerator for the map.
 448         *
 449         * @since 2.0
 450         *
 451         * @return               An instance of IMapEnumerator for this map, @n
 452         *                               else @c null if an exception occurs
 453         * @exception    E_SUCCESS               The method is successful.
 454         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 455         * @see                  IEnumerator
 456         */
 457         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 458
 459         /**
 460          * Gets the element deleter of the collection.
 461          *
 462          * @since 2.0
 463          *
 464          * @return              A function pointer to the existing element deleter
 465          */
 466         virtual DeleterFunctionType GetDeleter(void) const = 0;
 467
 468 protected:
 469         //
 470         // This method is for internal use only. Using this method can cause behavioral, security-related,
 471         // and consistency-related issues in the application.
 472         // This method is reserved and may change its name at any time without prior notice.
 473         //
 474         // @since 2.0
 475         //
 476         virtual void IMap_Reserved1(void) { }
 477
 478         //
 479         // This method is for internal use only. Using this method can cause behavioral, security-related,
 480         // and consistency-related issues in the application.
 481         // This method is reserved and may change its name at any time without prior notice.
 482         //
 483         // @since 2.0
 484         //
 485         virtual void IMap_Reserved2(void) { }
 486
 487 private:
 488         /**
 489          * Sets the element deleter of the collection.
 490          *
 491          * @since 2.0
 492          *
 493          * @param[in]   deleter A function pointer to the element deleter to set
 494          */
 495         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 496
 497 }; // IMap
 498
 499 }}} // Tizen::Base::Collection
 500
 501 #endif // _FBASE_COL_IMAP_H_