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