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