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