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