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()
 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             The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
 173          * @remarks             The %IList interface stores just the pointers to the elements in the map, not the elements themselves.
 174          * @remarks             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             The IList stores just the pointers to the elements in the map, not the elements themselves.
 187          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 188          * @see                 GetKeysN()
 189          */
 190         virtual IList* GetValuesN(void) const = 0;
 191
 192         /**
 193          * Removes the value associated with the specified key.
 194          *
 195          * @since 2.0
 196          *
 197          * @return              An error code
 198          * @param[in]   key The key to remove
 199          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 200          *                                                              else @c false
 201          * @exception   E_SUCCESS               The method is successful.
 202          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 203          *                                                              the comparer has failed to compare the keys.
 204          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 205          * @remarks             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
 206          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 207          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 208          * @remarks             Remove(key, @b true) internally works as the below code:
 209          * @code
 210          * DeleterFunctionType deleter = GetDeleter();
 211          * SetDeleter(SingleObjectDeleter);
 212          * Remove(key);
 213          * SetDeleter(deleter);
 214          * @endcode
 215          * @remarks             Remove(key, @b false) internally works as the below code:
 216          * @code
 217          * DeleterFunctionType deleter = GetDeleter();
 218          * SetDeleter(NoOpDeleter);
 219          * Remove(key);
 220          * SetDeleter(deleter);
 221          * @endcode
 222          * @see                 Add()
 223          */
 224         result Remove(const Object& key, bool forceDeletion)
 225         {
 226                 DeleterFunctionType deleter = GetDeleter();
 227
 228                 if (forceDeletion)
 229                 {
 230                         SetDeleter(SingleObjectDeleter);
 231                 }
 232                 else
 233                 {
 234                         SetDeleter(NoOpDeleter);
 235                 }
 236
 237                 result r = Remove(key);
 238                 SetDeleter(deleter);
 239                 return r;
 240         }
 241
 242         /**
 243          * Removes the value associated with the specified key.
 244          *
 245          * @since 2.0
 246          *
 247          * @return              An error code
 248          * @param[in]   key The key for which the value is to remove
 249          * @exception   E_SUCCESS               The method is successful.
 250          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 251          *                                                              the comparer has failed to compare the keys.
 252          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 253          * @see                 Add()
 254          */
 255         virtual result Remove(const Object& key) = 0;
 256
 257         /**
 258          * Removes all the object pointers in the collection. @n
 259          * 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.
 260          *
 261          * @since 2.0
 262          *
 263          * @param[in]   forceDeletion           Set to @c true to deallocate all the objects, @n
 264          *                                                              else @c false
 265          * @remarks             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
 266          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 267          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 268          * @remarks             RemoveAll(@b true) internally works as the below code:
 269          * @code
 270          * DeleterFunctionType deleter = GetDeleter();
 271          * SetDeleter(SingleObjectDeleter);
 272          * RemoveAll();
 273          * SetDeleter(deleter);
 274          * @endcode
 275          * @remarks             RemoveAll(@b false) internally works as the below code:
 276          * @code
 277          * DeleterFunctionType deleter = GetDeleter();
 278          * SetDeleter(NoOpDeleter);
 279          * RemoveAll();
 280          * SetDeleter(deleter);
 281          * @endcode
 282          */
 283         void RemoveAll(bool forceDeletion)
 284         {
 285                 DeleterFunctionType deleter = GetDeleter();
 286
 287                 if (forceDeletion)
 288                 {
 289                         SetDeleter(SingleObjectDeleter);
 290                 }
 291                 else
 292                 {
 293                         SetDeleter(NoOpDeleter);
 294                 }
 295
 296                 RemoveAll();
 297                 SetDeleter(deleter);
 298         }
 299
 300         /**
 301          * Removes all the object pointers in the collection. @n
 302          *
 303          * @since 2.0
 304          */
 305         virtual void RemoveAll(void) = 0;
 306
 307         /**
 308          * Replaces the value associated with the specified key with the specified value.
 309          *
 310          * @since 2.0
 311          *
 312          * @return              An error code
 313          * @param[in]   key     The key for which the value is to replace
 314          * @param[in]   value   The new value
 315          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 316          *                                                              else @c false
 317          * @exception   E_SUCCESS               The method is successful.
 318          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 319          *                                                              the comparer has failed to compare the keys.
 320          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 321          * @remarks     Use the Add() method to add a new key-value pair.
 322          * @remarks             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
 323          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
 324          *                              If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
 325          * @remarks     SetValue(key, value, @b true) internally works as the below code:
 326          * @code
 327          * DeleterFunctionType deleter = GetDeleter();
 328          * SetDeleter(SingleObjectDeleter);
 329          * SetValue(key, const_cast< Object* >(&value));
 330          * SetDeleter(deleter);
 331          * @endcode
 332          * @remarks     SetValue(key, value, @b false) internally works as the below code:
 333          * @code
 334          * DeleterFunctionType deleter = GetDeleter();
 335          * SetDeleter(NoOpDeleter);
 336          * SetValue(key, const_cast< Object* >(&value));
 337          * SetDeleter(deleter);
 338          * @endcode
 339          * @see         Add()
 340          * @see         GetValue()
 341          */
 342         result SetValue(const Object& key, const Object& value, bool forceDeletion = false)
 343         {
 344                 DeleterFunctionType deleter = GetDeleter();
 345
 346                 if (forceDeletion)
 347                 {
 348                         SetDeleter(SingleObjectDeleter);
 349                 }
 350                 else
 351                 {
 352                         SetDeleter(NoOpDeleter);
 353                 }
 354
 355                 result r = SetValue(key, const_cast< Object* >(&value));
 356                 SetDeleter(deleter);
 357                 return r;
 358         }
 359
 360         /**
 361          * Replaces the value associated with the specified key with the specified value.
 362          *
 363          * @since 2.0
 364          *
 365          * @return              An error code
 366          * @param[in] key               The key for which the value is to replace
 367          * @param[in]   pValue  The pointer to new value
 368          * @exception   E_SUCCESS               The method is successful.
 369          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 370          *                                                              the comparer has failed to compare the keys.
 371          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 372          * @remarks     Use the Add() method to add a new key-value pair.
 373          * @see         Add()
 374          * @see         GetValue()
 375          */
 376         virtual result SetValue(const Object& key, Object* pValue) = 0;
 377
 378         /**
 379          * @if OSPDEPREC
 380          * Checks whether the map contains the specified key.
 381          *
 382          * @brief               <i> [Deprecated] </i>
 383          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 384          *                              The return type will be changed into boolean type and this method will return the result.
 385          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 386          * @since 2.0
 387          *
 388          * @return              An error code
 389          * @param[in]   key     The key to locate
 390          * @param[out]  out             Set to @c true if the map contains the specified key, @n
 391          *                                              else @c false
 392          * @exception   E_SUCCESS               The method is successful.
 393          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 394          *                                                              the comparer has failed to compare the keys.
 395          * @see                 ContainsValue()
 396          * @endif
 397          */
 398         result ContainsKey(const Object& key, bool& out) const
 399         {
 400                 out = ContainsKey(key);
 401                 result r = GetLastResult();
 402                 return r;
 403         }
 404
 405         /**
 406          * Checks whether the map contains the specified key.
 407          *
 408          * @since 2.0
 409          *
 410          * @return              @c true if the map contains the specified key, @n
 411          *                              else @c false
 412          * @param[in]   key     The key to locate
 413          * @exception   E_SUCCESS               The method is successful.
 414          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 415          *                                                              the comparer has failed to compare the keys.
 416          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 417          * @see                 ContainsValue()
 418          */
 419         virtual bool ContainsKey(const Object& key) const = 0;
 420
 421         /**
 422          * Checks whether the map contains the specified value.
 423          *
 424          * @since 2.0
 425          *
 426          * @return              @c true if the map contains the specified value, @n
 427          *                              else @c false
 428          * @param[in]   value   The value to locate
 429          *
 430          * @see                 ContainsKey()
 431          */
 432         virtual bool ContainsValue(const Object& value) const = 0;
 433
 434         /**
 435         * Gets an instance of the IMapEnumerator for the map.
 436         *
 437         * @since 2.0
 438         *
 439         * @return                       IMapEnumerator object of this map, @n
 440         *                               else @c null if an exception occurs
 441         * @exception    E_SUCCESS               The method is successful.
 442         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 443         * @see                  IEnumerator
 444         * @see                  IMapEnumerator
 445         */
 446         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 447
 448         /**
 449          * Gets the element deleter of the collection.
 450          *
 451          * @since 2.0
 452          *
 453          * @return              A function pointer to the existing element deleter
 454          */
 455         virtual DeleterFunctionType GetDeleter(void) const = 0;
 456
 457 protected:
 458         //
 459         // This method is for internal use only. Using this method can cause behavioral, security-related,
 460         // and consistency-related issues in the application.
 461         // This method is reserved and may change its name at any time without prior notice.
 462         //
 463         // @since 2.0
 464         //
 465         virtual void IMap_Reserved1(void) { }
 466
 467
 468         //
 469         // This method is for internal use only. Using this method can cause behavioral, security-related,
 470         // and consistency-related issues in the application.
 471         // This method is reserved and may change its name at any time without prior notice.
 472         //
 473         // @since 2.0
 474         //
 475         virtual void IMap_Reserved2(void) { }
 476
 477 private:
 478         /**
 479          * Sets the element deleter of the collection.
 480          *
 481          * @since 2.0
 482          *
 483          * @param[in]   deleter A function pointer to the element deleter to set
 484          */
 485         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 486
 487 }; // IMap
 488
 489 }}} // Tizen::Base::Collection
 490
 491 #endif // _FBASE_COL_IMAP_H_