inc/FBaseColIMap.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseColIMap.h
  20  * @brief               This is the header file for the %IMap interface.
  21  *
  22  * This header file contains the declarations of the %IMap interface.
  23  */
  24 #ifndef _FBASE_COL_IMAP_H_
  25 #define _FBASE_COL_IMAP_H_
  26
  27 #include <FBaseColICollection.h>
  28 #include <FBaseColTypes.h>
  29 #include <FBaseColIMapEnumerator.h>
  30 #include <FBaseObject.h>
  31
  32
  33 namespace Tizen { namespace Base { namespace Collection
  34 {
  35
  36 class IList;
  37 class MapEntry;
  38
  39 /**
  40  * @interface IMap
  41  * @brief       This interface represents a collection of key-value pairs.
  42  *
  43  * @since 2.0
  44  *
  45  * The %IMap interface abstracts a collection of key-value pairs. An %IMap instance
  46  * contains unique keys and each key maps to a single value.
  47  * The key and value cannot be a @c null reference.
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
  50  */
  51 class _OSP_EXPORT_ IMap
  52         : public virtual ICollection
  53 {
  54 public:
  55         /**
  56          * This polymorphic destructor should be overridden if required. @n
  57          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  58          *
  59          * @since 2.0
  60          */
  61         virtual ~IMap(void) {}
  62
  63         /**
  64          * @if OSPDEPREC
  65          * Adds the specified key-value pair to the map.
  66          *
  67          * @brief               <i> [Deprecated] </i>
  68          * @deprecated  This method is deprecated because it has a problem of const reference argument.
  69          *                              Instead of using this method, use Add(Object* pKey, Object* pValue).
  70          * @since 2.0
  71          *
  72          * @return              An error code
  73          * @param[in]   key     The key to add
  74          * @param[in]   value   The corresponding value to add
  75          * @exception   E_SUCCESS                       The method is successful.
  76          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  77          *                                                                      the comparer has failed to compare the keys.
  78          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key already exists.
  79          * @remarks             This method performs a shallow copy. It adds just the pointer; not the element itself.
  80          * @see Remove()
  81          * @endif
  82          */
  83         result Add(const Object& key, const Object& value)
  84         {
  85                 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
  86         }
  87
  88         /**
  89          * Adds the specified key-value pair to the map.
  90          *
  91          * @since 2.0
  92          *
  93          * @return              An error code
  94          * @param[in]   pKey    The pointer to key to add
  95          * @param[in]   pValue  The pointer to corresponding value to add
  96          * @exception   E_SUCCESS                       The method is successful.
  97          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  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; not the element itself.
 101          * @see Remove()
 102          */
 103         virtual result Add(Object* pKey, Object* pValue) = 0;
 104
 105         /**
 106          * Checks if the key exists. If the key doesn't exist, Add() is called. Unless, SetValue() is called.
 107          *
 108          * @since 2.0
 109          *
 110          * @return              An error code
 111          * @param[in]   pKey    The pointer to key to add
 112          * @param[in]   pValue  The pointer to corresponding value to add
 113          * @exception   E_SUCCESS                       The method is successful.
 114          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
 115          *                                                                      the comparer has failed to compare the keys.
 116          * @remarks     This method performs a shallow copy. It adds just the pointer; not the element itself.
 117          * @see                 Add()
 118          * @see                 SetValue()
 119          */
 120         result AddIfNotExistOrSet(Object* pKey, Object* pValue)
 121         {
 122                 if (!ContainsKey(*pKey))
 123                 {
 124                         return Add(pKey, pValue);
 125                 }
 126                 else
 127                 {
 128                         return SetValue(*pKey, pValue);
 129                 }
 130         }
 131
 132         /**
 133          * Gets the value associated with the specified key.
 134          *
 135          * @since 2.0
 136          *
 137          * @return              The value associated with the specified key, @n
 138          *                              else @c null if an exception occurs
 139          * @param[in]   key     The key to find the associated value
 140          * @exception   E_SUCCESS               The method is successful.
 141          * @exception   E_INVALID_ARG   The specified input parameter is invalid, or
 142          *                                                              the comparer has failed to compare the keys.
 143          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 144          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 145          * @see                 SetValue()
 146          */
 147         virtual const Object* GetValue(const Object& key) const = 0;
 148
 149         /**
 150          * Gets the value associated with the specified key.
 151          *
 152          * @since 2.0
 153          *
 154          * @return              The value associated with the specified key, @n
 155          *                              else @c null if an exception occurs
 156          * @param[in]   key     The key to find the associated value
 157          * @exception   E_SUCCESS               The method is successful.
 158          * @exception   E_INVALID_ARG   The specified input parameter is invalid, or
 159          *                                                              the comparer has failed to compare the keys.
 160          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 161          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 162          * @see                 SetValue()
 163          */
 164         virtual Object* GetValue(const Object& key) = 0;
 165
 166         /**
 167          * Gets a list of all the keys in the map.
 168          *
 169          * @since 2.0
 170          *
 171          * @return              A pointer to a list of all the keys in the map, @n
 172          *                              else @c null if an exception occurs
 173          * @remarks             The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
 174          * @remarks             The %IList interface stores just the pointers to the elements in the map, not the elements themselves.
 175          * @remarks             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             The IList stores just the pointers to the elements in the map, not the elements themselves.
 188          * @remarks             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             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
 207          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 208          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 209          * @remarks             Remove(key, @b true) internally works as the below code:
 210          * @code
 211          * DeleterFunctionType deleter = GetDeleter();
 212          * SetDeleter(SingleObjectDeleter);
 213          * Remove(key);
 214          * SetDeleter(deleter);
 215          * @endcode
 216          * @remarks             Remove(key, @b false) internally works as the below code:
 217          * @code
 218          * DeleterFunctionType deleter = GetDeleter();
 219          * SetDeleter(NoOpDeleter);
 220          * Remove(key);
 221          * SetDeleter(deleter);
 222          * @endcode
 223          * @see                 Add()
 224          */
 225         result Remove(const Object& key, bool forceDeletion)
 226         {
 227                 DeleterFunctionType deleter = GetDeleter();
 228
 229                 if (forceDeletion)
 230                 {
 231                         SetDeleter(SingleObjectDeleter);
 232                 }
 233                 else
 234                 {
 235                         SetDeleter(NoOpDeleter);
 236                 }
 237
 238                 result r = Remove(key);
 239                 SetDeleter(deleter);
 240                 return r;
 241         }
 242
 243         /**
 244          * Removes the value associated with the specified key.
 245          *
 246          * @since 2.0
 247          *
 248          * @return              An error code
 249          * @param[in]   key The key for which the value is to remove
 250          * @exception   E_SUCCESS               The method is successful.
 251          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 252          *                                                              the comparer has failed to compare the keys.
 253          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 254          * @see                 Add()
 255          */
 256         virtual result Remove(const Object& key) = 0;
 257
 258         /**
 259          * Removes all the object pointers in the collection. @n
 260          * 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.
 261          *
 262          * @since 2.0
 263          *
 264          * @param[in]   forceDeletion           Set to @c true to deallocate all the objects, @n
 265          *                                                              else @c false
 266          * @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
 267          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 268          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 269          * @remarks             RemoveAll(@b true) internally works as the below code:
 270          * @code
 271          * DeleterFunctionType deleter = GetDeleter();
 272          * SetDeleter(SingleObjectDeleter);
 273          * RemoveAll();
 274          * SetDeleter(deleter);
 275          * @endcode
 276          * @remarks             RemoveAll(@b false) internally works as the below code:
 277          * @code
 278          * DeleterFunctionType deleter = GetDeleter();
 279          * SetDeleter(NoOpDeleter);
 280          * RemoveAll();
 281          * SetDeleter(deleter);
 282          * @endcode
 283          */
 284         void RemoveAll(bool forceDeletion)
 285         {
 286                 DeleterFunctionType deleter = GetDeleter();
 287
 288                 if (forceDeletion)
 289                 {
 290                         SetDeleter(SingleObjectDeleter);
 291                 }
 292                 else
 293                 {
 294                         SetDeleter(NoOpDeleter);
 295                 }
 296
 297                 RemoveAll();
 298                 SetDeleter(deleter);
 299         }
 300
 301         /**
 302          * Removes all the object pointers in the collection. @n
 303          *
 304          * @since 2.0
 305          */
 306         virtual void RemoveAll(void) = 0;
 307
 308         /**
 309          * Replaces the value associated with the specified key with the specified value.
 310          *
 311          * @since 2.0
 312          *
 313          * @return              An error code
 314          * @param[in]   key     The key for which the value is to replace
 315          * @param[in]   value   The new value
 316          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 317          *                                                              else @c false
 318          * @exception   E_SUCCESS               The method is successful.
 319          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 320          *                                                              the comparer has failed to compare the keys.
 321          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 322          * @remarks     Use the Add() method to add a new key-value pair.
 323          * @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
 324          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
 325          *                              If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
 326          * @remarks     SetValue(key, value, @b true) internally works as the below code:
 327          * @code
 328          * DeleterFunctionType deleter = GetDeleter();
 329          * SetDeleter(SingleObjectDeleter);
 330          * SetValue(key, const_cast< Object* >(&value));
 331          * SetDeleter(deleter);
 332          * @endcode
 333          * @remarks     SetValue(key, value, @b false) internally works as the below code:
 334          * @code
 335          * DeleterFunctionType deleter = GetDeleter();
 336          * SetDeleter(NoOpDeleter);
 337          * SetValue(key, const_cast< Object* >(&value));
 338          * SetDeleter(deleter);
 339          * @endcode
 340          * @see         Add()
 341          * @see         GetValue()
 342          */
 343         result SetValue(const Object& key, const Object& value, bool forceDeletion = false)
 344         {
 345                 DeleterFunctionType deleter = GetDeleter();
 346
 347                 if (forceDeletion)
 348                 {
 349                         SetDeleter(SingleObjectDeleter);
 350                 }
 351                 else
 352                 {
 353                         SetDeleter(NoOpDeleter);
 354                 }
 355
 356                 result r = SetValue(key, const_cast< Object* >(&value));
 357                 SetDeleter(deleter);
 358                 return r;
 359         }
 360
 361         /**
 362          * Replaces the value associated with the specified key with the specified value.
 363          *
 364          * @since 2.0
 365          *
 366          * @return              An error code
 367          * @param[in] key               The key for which the value is to replace
 368          * @param[in]   pValue  The pointer to new value
 369          * @exception   E_SUCCESS               The method is successful.
 370          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 371          *                                                              the comparer has failed to compare the keys.
 372          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 373          * @remarks     Use the Add() method to add a new key-value pair.
 374          * @see         Add()
 375          * @see         GetValue()
 376          */
 377         virtual result SetValue(const Object& key, Object* pValue) = 0;
 378
 379         /**
 380          * @if OSPDEPREC
 381          * Checks whether the map contains the specified key.
 382          *
 383          * @brief               <i> [Deprecated] </i>
 384          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 385          *                              The return type will be changed into boolean type and this method will return the result.
 386          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 387          * @since 2.0
 388          *
 389          * @return              An error code
 390          * @param[in]   key     The key to locate
 391          * @param[out]  out             Set to @c true if the map contains the specified key, @n
 392          *                                              else @c false
 393          * @exception   E_SUCCESS               The method is successful.
 394          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 395          *                                                              the comparer has failed to compare the keys.
 396          * @see                 ContainsValue()
 397          * @endif
 398          */
 399         result ContainsKey(const Object& key, bool& out) const
 400         {
 401                 out = ContainsKey(key);
 402                 result r = GetLastResult();
 403                 return r;
 404         }
 405
 406         /**
 407          * Checks whether the map contains the specified key.
 408          *
 409          * @since 2.0
 410          *
 411          * @return              @c true if the map contains the specified key, @n
 412          *                              else @c false
 413          * @param[in]   key     The key to locate
 414          * @exception   E_SUCCESS               The method is successful.
 415          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 416          *                                                              the comparer has failed to compare the keys.
 417          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 418          * @see                 ContainsValue()
 419          */
 420         virtual bool ContainsKey(const Object& key) const = 0;
 421
 422         /**
 423          * Checks whether the map contains the specified value.
 424          *
 425          * @since 2.0
 426          *
 427          * @return              @c true if the map contains the specified value, @n
 428          *                              else @c false
 429          * @param[in]   value   The value to locate
 430          *
 431          * @see                 ContainsKey()
 432          */
 433         virtual bool ContainsValue(const Object& value) const = 0;
 434
 435         /**
 436         * Gets an instance of the IMapEnumerator for the map.
 437         *
 438         * @since 2.0
 439         *
 440         * @return                       IMapEnumerator object of this map, @n
 441         *                               else @c null if an exception occurs
 442         * @exception    E_SUCCESS               The method is successful.
 443         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 444         * @see                  IEnumerator
 445         * @see                  IMapEnumerator
 446         */
 447         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 448
 449         /**
 450          * Gets the element deleter of the collection.
 451          *
 452          * @since 2.0
 453          *
 454          * @return              A function pointer to the existing element deleter
 455          */
 456         virtual DeleterFunctionType GetDeleter(void) const = 0;
 457
 458 protected:
 459         //
 460         // This method is for internal use only. Using this method can cause behavioral, security-related,
 461         // and consistency-related issues in the application.
 462         // This method is reserved and may change its name at any time without prior notice.
 463         //
 464         // @since 2.0
 465         //
 466         virtual void IMap_Reserved1(void) { }
 467
 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_