inc/FBaseColIMultiMap.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                FBaseColIMultiMap.h
  19  * @brief               This is the header file for the %IMultiMap interface.
  20  *
  21  * This header file contains the declarations of the %IMultiMap interface.
  22  */
  23 #ifndef _FBASE_COL_IMULTI_MAP_H_
  24 #define _FBASE_COL_IMULTI_MAP_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 IMultiMap
  40  * @brief       This interface represents a collection of key-value pairs.
  41  *
  42  * @since 2.0
  43  *
  44  * The %IMultiMap interface abstracts a collection of key-value pairs.
  45  * There is no limit on the number of elements with the same key, but duplicated elements with the same key are not allowed.
  46  * The key and value cannot be a @c null reference.
  47  * @n
  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  */
  51 class _OSP_EXPORT_ IMultiMap
  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 ~IMultiMap(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 and @c value already exist.
  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 and @c pValue already exist.
 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          * Gets the number of values stored in the map.
 107          *
 108          * @since 2.0
 109          *
 110          * @return              The number of values currently stored in the map
 111          */
 112         virtual int GetCount(void) const = 0;
 113
 114         /**
 115          * Gets the number of values with keys matching the specified key.
 116          *
 117          * @since 2.0
 118          *
 119          * @return              The number of values with keys matching the specified key
 120          * @param[in]   key     The key to locate in the map
 121          * @param[out]  count   The number of values with keys matching the specified key
 122          * @exception   E_SUCCESS                       The method is successful.
 123          * @exception   E_INVALID_ARG           The specified input parameter is invalid, or
 124          *                                                                      the comparer has failed to compare the keys.
 125          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
 126          */
 127         virtual result GetCount(const Object& key, int& count) const = 0;
 128
 129         /**
 130          * Gets an enumerator of the values associated with the specified key.
 131          *
 132          * @since 2.0
 133          *
 134          * @return              An instance of the IEnumerator derived class with the values associated with the specified key, @n
 135          *                              else @c null if an exception occurs
 136          * @param[in]   key                     The key to locate in the map
 137          * @exception   E_SUCCESS               The method is successful.
 138          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 139          *                                                              the comparer has failed to compare the keys.
 140          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 141          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 142          */
 143         virtual IEnumerator* GetValuesN(const Object& key) const = 0;
 144
 145         /**
 146          * Gets a list of all unique keys in the map.
 147          *
 148          * @since 2.0
 149          *
 150          * @return              A pointer to a list of all unique keys in the map, @n
 151          *                              else @c null if an exception occurs
 152          * @remarks             The %IList stores just the pointers to the elements in the map, not the elements themselves.
 153          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 154          * @see                 GetValuesN()
 155          */
 156         virtual IList* GetKeysN(void) const = 0;
 157
 158         /**
 159          * Gets a list of all the values in the map.
 160          *
 161          * @since 2.0
 162          *
 163          * @return              A pointer to a list of all the values in the map, @n
 164          *                              else @c null if an exception occurs
 165          * @remarks             The IList stores just the pointers to the elements in the map, not the elements themselves.
 166          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 167          * @see                 SetValue()
 168          */
 169         virtual IList* GetValuesN(void) const = 0;
 170
 171         /**
 172          * Removes all the values associated with the specified key.
 173          *
 174          * @since 2.0
 175          *
 176          * @return              An error code
 177          * @param[in]   key The key for which the associated values need to remove
 178          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 179          *                                                              else @c false
 180          * @exception   E_SUCCESS               The method is successful.
 181          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 182          *                                                              the comparer has failed to compare the keys.
 183          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 184          * @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
 185          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 186          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 187          * @remarks             Remove(key, @b true) internally works as the below code:
 188          * @code
 189          * DeleterFunctionType deleter = GetDeleter();
 190          * SetDeleter(SingleObjectDeleter);
 191          * Remove(key);
 192          * SetDeleter(deleter);
 193          * @endcode
 194          * @remarks             Remove(key, @b false) internally works as the below code:
 195          * @code
 196          * DeleterFunctionType deleter = GetDeleter();
 197          * SetDeleter(NoOpDeleter);
 198          * Remove(key);
 199          * SetDeleter(deleter);
 200          * @endcode
 201          * @see                 Add()
 202          */
 203         result Remove(const Object& key, bool forceDeletion)
 204         {
 205                 DeleterFunctionType deleter = GetDeleter();
 206
 207                 if (forceDeletion)
 208                 {
 209                         SetDeleter(SingleObjectDeleter);
 210                 }
 211                 else
 212                 {
 213                         SetDeleter(NoOpDeleter);
 214                 }
 215
 216                 result r = Remove(key);
 217                 SetDeleter(deleter);
 218                 return r;
 219         }
 220
 221         /**
 222          * Removes all the values associated with the specified key.
 223          *
 224          * @since 2.0
 225          *
 226          * @return              An error code
 227          * @param[in]   key The key for which the associated values need to remove
 228          * @exception   E_SUCCESS               The method is successful.
 229          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 230          *                                                              the comparer has failed to compare the keys.
 231          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 232          * @see                 Add()
 233          */
 234         virtual result Remove(const Object& key) = 0;
 235
 236         /**
 237          * Removes the specified value associated with the specified key. @n
 238          * The key is also removed if there are no more values associated with it.
 239          *
 240          * @since 2.0
 241          *
 242          * @return              An error code
 243          * @param[in]   key     The key for which the mapping is to remove from the map
 244          * @param[in]   value   The value to remove
 245          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 246          *                                                              else @c false
 247          * @exception   E_SUCCESS               The method is successful.
 248          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 249          *                                                              the comparer has failed to compare the keys.
 250          * @exception   E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
 251          * @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
 252          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 253          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 254          * @remarks             Remove(key, value, @b true) internally works as the below code:
 255          * @code
 256          * DeleterFunctionType deleter = GetDeleter();
 257          * SetDeleter(SingleObjectDeleter);
 258          * Remove(key, value);
 259          * SetDeleter(deleter);
 260          * @endcode
 261          * @remarks             Remove(key, value, @b false) internally works as the below code:
 262          * @code
 263          * DeleterFunctionType deleter = GetDeleter();
 264          * SetDeleter(NoOpDeleter);
 265          * Remove(key, value);
 266          * SetDeleter(deleter);
 267          * @endcode
 268          * @see                 Add()
 269          */
 270         result Remove(const Object& key, const Object& value, bool forceDeletion)
 271         {
 272                 DeleterFunctionType deleter = GetDeleter();
 273
 274                 if (forceDeletion)
 275                 {
 276                         SetDeleter(SingleObjectDeleter);
 277                 }
 278                 else
 279                 {
 280                         SetDeleter(NoOpDeleter);
 281                 }
 282
 283                 result r = Remove(key, value);
 284                 SetDeleter(deleter);
 285                 return r;
 286         }
 287
 288         /**
 289          * Removes the specified value associated with the specified key. @n
 290          * The key is also removed if there are no more values associated with it.
 291          *
 292          * @since 2.0
 293          *
 294          * @return              An error code
 295          * @param[in]   key     The key for which the mapping is to remove from the map
 296          * @param[in]   value   The value to remove
 297          * @exception   E_SUCCESS               The method is successful.
 298          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 299          *                                                              the comparer has failed to compare the keys.
 300          * @exception   E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
 301          * @see                 Add()
 302          */
 303         virtual result Remove(const Object& key, const Object& value) = 0;
 304
 305         /**
 306          * Removes all the object pointers in the collection. @n
 307          * 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.
 308          *
 309          * @since 2.0
 310          *
 311          * @param[in]   forceDeletion           Set to @c true to deallocate all objects, @n
 312          *                                                              else @c false
 313          * @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
 314          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
 315          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 316          * @remarks             RemoveAll(@b true) internally works as the below code:
 317          * @code
 318          * DeleterFunctionType deleter = GetDeleter();
 319          * SetDeleter(SingleObjectDeleter);
 320          * RemoveAll();
 321          * SetDeleter(deleter);
 322          * @endcode
 323          * @remarks             RemoveAll(@b false) internally works as the below code:
 324          * @code
 325          * DeleterFunctionType deleter = GetDeleter();
 326          * SetDeleter(NoOpDeleter);
 327          * RemoveAll();
 328          * SetDeleter(deleter);
 329          * @endcode
 330          */
 331         void RemoveAll(bool forceDeletion)
 332         {
 333                 DeleterFunctionType deleter = GetDeleter();
 334
 335                 if (forceDeletion)
 336                 {
 337                         SetDeleter(SingleObjectDeleter);
 338                 }
 339                 else
 340                 {
 341                         SetDeleter(NoOpDeleter);
 342                 }
 343
 344                 RemoveAll();
 345                 SetDeleter(deleter);
 346         }
 347
 348         /**
 349          * Removes all the object pointers in the collection. @n
 350          * This method can be called before deleting the collection.
 351          *
 352          * @since 2.0
 353          */
 354         virtual void RemoveAll(void) = 0;
 355
 356         /**
 357          * Replaces the specified value associated with the specified key with a new value.
 358          *
 359          * @since 2.0
 360          *
 361          * @return              An error code
 362          * @param[in]   key     The key for which the associated value needs to replace
 363          * @param[in]   value   The value associated with the key
 364          * @param[in]   newValue        The new value
 365          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 366          *                                                              else @c false
 367          * @exception   E_SUCCESS               The method is successful.
 368          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 369          *                                                              the comparer has failed to compare the keys.
 370          * @exception   E_OBJ_NOT_FOUND The key-value pair is not found in the map.
 371          * @remarks             Use the Add() method to add a new key-value pair.
 372          * @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
 373          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
 374          *                              If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
 375          * @remarks             SetValue(key, value, newValue, @b true) internally works as the below code:
 376          * @code
 377          * DeleterFunctionType deleter = GetDeleter();
 378          * SetDeleter(SingleObjectDeleter);
 379          * SetValue(key, value, const_cast< Object* >(&newValue));
 380          * SetDeleter(deleter);
 381          * @endcode
 382          * @remarks             SetValue(key, value, newValue, @b false) internally works as the below code:
 383          * @code
 384          * DeleterFunctionType deleter = GetDeleter();
 385          * SetDeleter(NoOpDeleter);
 386          * SetValue(key, value, const_cast< Object* >(&newValue));
 387          * SetDeleter(deleter);
 388          * @endcode
 389          * @see                 Add()
 390          * @see                 GetValuesN()
 391          */
 392         result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
 393         {
 394                 DeleterFunctionType deleter = GetDeleter();
 395
 396                 if (forceDeletion)
 397                 {
 398                         SetDeleter(SingleObjectDeleter);
 399                 }
 400                 else
 401                 {
 402                         SetDeleter(NoOpDeleter);
 403                 }
 404
 405                 result r = SetValue(key, value, const_cast< Object* >(&newValue));
 406                 SetDeleter(deleter);
 407                 return r;
 408         }
 409
 410         /**
 411          * Replaces the specified value associated with the specified key with a new value.
 412          *
 413          * @since 2.0
 414          *
 415          * @return              An error code
 416          * @param[in]   key     The key for which the associated value needs to replace
 417          * @param[in]   value   The value associated with the key
 418          * @param[in]   pNewValue       The pointer to new value
 419          * @exception   E_SUCCESS               The method is successful.
 420          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 421          *                                                              the comparer has failed to compare the keys.
 422          * @exception   E_OBJ_NOT_FOUND The key-value pair is not found in the map.
 423          * @remarks             Use the Add() method to add a new key-value pair.
 424          * @see                 Add()
 425          * @see                 GetValuesN()
 426          */
 427         virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
 428
 429         /**
 430          * @if OSPDEPREC
 431          * Checks whether the map contains the specified key-value pair.
 432          *
 433          * @brief               <i> [Deprecated] </i>
 434          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 435          *                              The return type will be changed into boolean type and this method will return the result.
 436          *                              Instead of using this method, use bool Contains(const Object& key, const Object& value).
 437          * @since 2.0
 438          *
 439          * @return              An error code
 440          * @param[in]   key     The key to locate
 441          * @param[in]   value   The value to locate
 442          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
 443          *                                              else @c false
 444          * @exception   E_SUCCESS               The method is successful.
 445          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 446          *                                                              the comparer has failed to compare the keys.
 447          * @see                 ContainsKey()
 448          * @see                 ContainsValue()
 449          * @endif
 450          */
 451         result Contains(const Object& key, const Object& value, bool& out) const
 452         {
 453                 out = Contains(key, value);
 454                 result r = GetLastResult();
 455                 return r;
 456         }
 457
 458         /**
 459          * Checks whether the map contains the specified key-value pair.
 460          *
 461          * @since 2.0
 462          *
 463          * @return              @c true if the map contains the specified key-value pair, @n
 464          *                              else @c false
 465          * @param[in]   key     The key to locate
 466          * @param[in]   value   The value to locate
 467          * @exception   E_SUCCESS               The method is successful.
 468          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 469          *                                                              the comparer has failed to compare the keys.
 470          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 471          * @see                 ContainsKey()
 472          * @see                 ContainsValue()
 473          */
 474         virtual bool Contains(const Object& key, const Object& value) const = 0;
 475
 476         /**
 477          * @if OSPDEPREC
 478          * Checks whether the map contains the specified key.
 479          *
 480          * @brief               <i> [Deprecated] </i>
 481          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 482          *                              The return type will be changed into boolean type and this method will return the result.
 483          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 484          * @since 2.0
 485          *
 486          * @return              An error code
 487          * @param[in]   key     The key to locate
 488          * @param[out]  out             Set to @c true if the map contains the specified key, @n
 489          *                                              else @c false
 490          * @exception   E_SUCCESS               The method is successful.
 491          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 492          *                                                              the comparer has failed to compare the keys.
 493          * @see                 ContainsValue()
 494          * @see                 Contains()
 495          * @endif
 496          */
 497         result ContainsKey(const Object& key, bool& out) const
 498         {
 499                 out = ContainsKey(key);
 500                 result r = GetLastResult();
 501                 return r;
 502         }
 503
 504         /**
 505          * Checks whether the map contains the specified key.
 506          *
 507          * @since 2.0
 508          *
 509          * @return              @c true if the map contains the specified key, @n
 510          *                              else @c false
 511          * @param[in]   key     The key to locate
 512          * @exception   E_SUCCESS               The method is successful.
 513          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 514          *                                                              the comparer has failed to compare the keys.
 515          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 516          * @see                 ContainsValue()
 517          * @see                 Contains()
 518          */
 519         virtual bool ContainsKey(const Object& key) const = 0;
 520
 521         /**
 522          * Checks whether the map contains the specified value.
 523          *
 524          * @since 2.0
 525          *
 526          * @return              @c true if the map contains the specified value, @n
 527          *                              else @c false
 528          * @param[in]   value   The value to locate
 529          *
 530          * @see                 ContainsKey()
 531          * @see                 Contains()
 532          */
 533         virtual bool ContainsValue(const Object& value) const = 0;
 534
 535         /**
 536          * Gets an enumerator of the map.
 537          *
 538          * @since 2.0
 539          *
 540          * @return              An instance of the IMapEnumerator class for the map, @n
 541          *                              else @c null if an exception occurs
 542          * @exception   E_SUCCESS               The method is successful.
 543          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
 544          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
 545          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 546          * @see                 IEnumerator
 547          * @see                 IMapEnumerator
 548          */
 549         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 550
 551         /**
 552          * Gets the element deleter of the collection.
 553          *
 554          * @since 2.0
 555          *
 556          * @return              A function pointer to the existing element deleter
 557          */
 558         virtual DeleterFunctionType GetDeleter(void) const = 0;
 559
 560 protected:
 561         //
 562         // This method is for internal use only. Using this method can cause behavioral, security-related,
 563         // and consistency-related issues in the application.
 564         // This method is reserved and may change its name at any time without prior notice.
 565         //
 566         // @since 2.0
 567         //
 568         virtual void IMultiMap_Reserved1(void) { }
 569
 570
 571         //
 572         // This method is for internal use only. Using this method can cause behavioral, security-related,
 573         // and consistency-related issues in the application.
 574         // This method is reserved and may change its name at any time without prior notice.
 575         //
 576         // @since 2.0
 577         //
 578         virtual void IMultiMap_Reserved2(void) { }
 579
 580 private:
 581         /**
 582          * Sets the element deleter of the collection.
 583          *
 584          * @since 2.0
 585          *
 586          * @param[in]   deleter A function pointer to the element deleter to set
 587          */
 588         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 589
 590 }; // IMultiMap
 591
 592 }}} // Tizen::Base::Collection
 593
 594 #endif // _FBASE_COL_IMULTI_MAP_H_