inc/FBaseColIMultiMap.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseColIMultiMap.h
  20  * @brief               This is the header file for the %IMultiMap interface.
  21  *
  22  * This header file contains the declarations of the %IMultiMap interface.
  23  */
  24 #ifndef _FBASE_COL_IMULTI_MAP_H_
  25 #define _FBASE_COL_IMULTI_MAP_H_
  26
  27 #include <FBaseColICollection.h>
  28 #include <FBaseColTypes.h>
  29 #include <FBaseColIMapEnumerator.h>
  30 #include <FBaseObject.h>
  31
  32
  33 namespace Tizen { namespace Base { namespace Collection
  34 {
  35
  36 class IList;
  37 class MapEntry;
  38
  39 /**
  40  * @interface IMultiMap
  41  * @brief       This interface represents a collection of key-value pairs.
  42  *
  43  * @since 2.0
  44  *
  45  * The %IMultiMap interface abstracts a collection of key-value pairs.
  46  * There is no limit on the number of elements with the same key, but duplicated elements with the same key are not allowed.
  47  * The key and value cannot be a @c null reference.
  48  * @n
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
  50  *
  51  */
  52 class _OSP_EXPORT_ IMultiMap
  53         : public virtual ICollection
  54 {
  55 public:
  56         /**
  57          * This polymorphic destructor should be overridden if required. @n
  58          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  59          *
  60          * @since 2.0
  61          */
  62         virtual ~IMultiMap(void) {}
  63
  64         /**
  65          * @if OSPDEPREC
  66          * Adds the specified key-value pair to the map.
  67          *
  68          * @brief               <i> [Deprecated] </i>
  69          * @deprecated  This method is deprecated because it has a problem of const reference argument.
  70          *                              Instead of using this method, use Add(Object* pKey, Object* pValue).
  71          * @since 2.0
  72          *
  73          * @return              An error code
  74          * @param[in]   key     The key to add
  75          * @param[in]   value   The corresponding value to add
  76          * @exception   E_SUCCESS                       The method is successful.
  77          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  78          *                                                                      the comparer has failed to compare the keys.
  79          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key and @c value already exist.
  80          * @remarks             This method performs a shallow copy. It adds just the pointer; not the element itself.
  81          * @see Remove()
  82          * @endif
  83          */
  84         result Add(const Object& key, const Object& value)
  85         {
  86                 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
  87         }
  88
  89         /**
  90          * Adds the specified key-value pair to the map.
  91          *
  92          * @since 2.0
  93          *
  94          * @return              An error code
  95          * @param[in]   pKey    The pointer to key to add
  96          * @param[in]   pValue  The pointer to corresponding value to add
  97          * @exception   E_SUCCESS                       The method is successful.
  98          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  99          *                                                                      the comparer has failed to compare the keys.
 100          * @exception   E_OBJ_ALREADY_EXIST     The specified @c pKey and @c pValue already exist.
 101          * @remarks             This method performs a shallow copy. It adds just the pointer; not the element itself.
 102          * @see Remove()
 103          */
 104         virtual result Add(Object* pKey, Object* pValue) = 0;
 105
 106         /**
 107          * Gets the number of values stored in the map.
 108          *
 109          * @since 2.0
 110          *
 111          * @return              The number of values currently stored in the map
 112          */
 113         virtual int GetCount(void) const = 0;
 114
 115         /**
 116          * Gets the number of values with keys matching the specified key.
 117          *
 118          * @since 2.0
 119          *
 120          * @return              The number of values with keys matching the specified key
 121          * @param[in]   key     The key to locate in the map
 122          * @param[out]  count   The number of values with keys matching the specified key
 123          * @exception   E_SUCCESS                       The method is successful.
 124          * @exception   E_INVALID_ARG           The specified input parameter is invalid, or
 125          *                                                                      the comparer has failed to compare the keys.
 126          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
 127          */
 128         virtual result GetCount(const Object& key, int& count) const = 0;
 129
 130         /**
 131          * Gets an enumerator of the values associated with the specified key.
 132          *
 133          * @since 2.0
 134          *
 135          * @return              An instance of the IEnumerator derived class with the values associated with the specified key, @n
 136          *                              else @c null if an exception occurs
 137          * @param[in]   key                     The key to locate in the map
 138          * @exception   E_SUCCESS               The method is successful.
 139          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 140          *                                                              the comparer has failed to compare the keys.
 141          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 142          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 143          */
 144         virtual IEnumerator* GetValuesN(const Object& key) const = 0;
 145
 146         /**
 147          * Gets a list of all the keys in the map.
 148          *
 149          * @since 2.0
 150          *
 151          * @return              A pointer to a list of all the keys in the map, @n
 152          *                              else @c null if an exception occurs
 153          * @remarks             The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
 154          * @remarks             The %IList stores just the pointers to the elements in the map, not the elements themselves.
 155          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 156          * @see                 GetValuesN()
 157          */
 158         virtual IList* GetKeysN(void) const = 0;
 159
 160         /**
 161          * Gets a list of all the values in the map.
 162          *
 163          * @since 2.0
 164          *
 165          * @return              A pointer to a list of all the values in the map, @n
 166          *                              else @c null if an exception occurs
 167          * @remarks             The IList stores just the pointers to the elements in the map, not the elements themselves.
 168          * @remarks             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             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          * @remarks             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          * @remarks             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()
 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()
 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             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
 254          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method.@n
 255          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 256          * @remarks             Remove(key, value, @b true) internally works as the below code:
 257          * @code
 258          * DeleterFunctionType deleter = GetDeleter();
 259          * SetDeleter(SingleObjectDeleter);
 260          * Remove(key, value);
 261          * SetDeleter(deleter);
 262          * @endcode
 263          * @remarks             Remove(key, value, @b false) internally works as the below code:
 264          * @code
 265          * DeleterFunctionType deleter = GetDeleter();
 266          * SetDeleter(NoOpDeleter);
 267          * Remove(key, value);
 268          * SetDeleter(deleter);
 269          * @endcode
 270          * @see                 Add()
 271          */
 272         result Remove(const Object& key, const Object& value, bool forceDeletion)
 273         {
 274                 DeleterFunctionType deleter = GetDeleter();
 275
 276                 if (forceDeletion)
 277                 {
 278                         SetDeleter(SingleObjectDeleter);
 279                 }
 280                 else
 281                 {
 282                         SetDeleter(NoOpDeleter);
 283                 }
 284
 285                 result r = Remove(key, value);
 286                 SetDeleter(deleter);
 287                 return r;
 288         }
 289
 290         /**
 291          * Removes the specified value associated with the specified key. @n
 292          * The key is also removed if there are no more values associated with it.
 293          *
 294          * @since 2.0
 295          *
 296          * @return              An error code
 297          * @param[in]   key     The key for which the mapping is to remove from the map
 298          * @param[in]   value   The value to remove
 299          * @exception   E_SUCCESS               The method is successful.
 300          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 301          *                                                              the comparer has failed to compare the keys.
 302          * @exception   E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
 303          * @see                 Add()
 304          */
 305         virtual result Remove(const Object& key, const Object& value) = 0;
 306
 307         /**
 308          * Removes all the object pointers in the collection. @n
 309          * 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.
 310          *
 311          * @since 2.0
 312          *
 313          * @param[in]   forceDeletion           Set to @c true to deallocate all objects, @n
 314          *                                                              else @c false
 315          * @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
 316          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method.@n
 317          *                              If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
 318          * @remarks             RemoveAll(@b true) internally works as the below code:
 319          * @code
 320          * DeleterFunctionType deleter = GetDeleter();
 321          * SetDeleter(SingleObjectDeleter);
 322          * RemoveAll();
 323          * SetDeleter(deleter);
 324          * @endcode
 325          * @remarks             RemoveAll(@b false) internally works as the below code:
 326          * @code
 327          * DeleterFunctionType deleter = GetDeleter();
 328          * SetDeleter(NoOpDeleter);
 329          * RemoveAll();
 330          * SetDeleter(deleter);
 331          * @endcode
 332          */
 333         void RemoveAll(bool forceDeletion)
 334         {
 335                 DeleterFunctionType deleter = GetDeleter();
 336
 337                 if (forceDeletion)
 338                 {
 339                         SetDeleter(SingleObjectDeleter);
 340                 }
 341                 else
 342                 {
 343                         SetDeleter(NoOpDeleter);
 344                 }
 345
 346                 RemoveAll();
 347                 SetDeleter(deleter);
 348         }
 349
 350         /**
 351          * Removes all the object pointers in the collection. @n
 352          * This method can be called before deleting the collection.
 353          *
 354          * @since 2.0
 355          */
 356         virtual void RemoveAll(void) = 0;
 357
 358         /**
 359          * Replaces the specified value associated with the specified key with a new value.
 360          *
 361          * @since 2.0
 362          *
 363          * @return              An error code
 364          * @param[in]   key     The key for which the associated value needs to replace
 365          * @param[in]   value   The value associated with the key
 366          * @param[in]   newValue        The new value
 367          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 368          *                                                              else @c false
 369          * @exception   E_SUCCESS               The method is successful.
 370          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 371          *                                                              the comparer has failed to compare the keys.
 372          * @exception   E_OBJ_NOT_FOUND The key-value pair is not found in the map.
 373          * @remarks             Use the Add() method to add a new key-value pair.
 374          * @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
 375          *                              The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method.@n
 376          *                              If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
 377          * @remarks             SetValue(key, value, newValue, @b true) internally works as the below code:
 378          * @code
 379          * DeleterFunctionType deleter = GetDeleter();
 380          * SetDeleter(SingleObjectDeleter);
 381          * SetValue(key, value, const_cast< Object* >(&newValue));
 382          * SetDeleter(deleter);
 383          * @endcode
 384          * @remarks             SetValue(key, value, newValue, @b false) internally works as the below code:
 385          * @code
 386          * DeleterFunctionType deleter = GetDeleter();
 387          * SetDeleter(NoOpDeleter);
 388          * SetValue(key, value, const_cast< Object* >(&newValue));
 389          * SetDeleter(deleter);
 390          * @endcode
 391          * @see                 Add()
 392          * @see                 GetValuesN()
 393          */
 394         result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
 395         {
 396                 DeleterFunctionType deleter = GetDeleter();
 397
 398                 if (forceDeletion)
 399                 {
 400                         SetDeleter(SingleObjectDeleter);
 401                 }
 402                 else
 403                 {
 404                         SetDeleter(NoOpDeleter);
 405                 }
 406
 407                 result r = SetValue(key, value, const_cast< Object* >(&newValue));
 408                 SetDeleter(deleter);
 409                 return r;
 410         }
 411
 412         /**
 413          * Replaces the specified value associated with the specified key with a new value.
 414          *
 415          * @since 2.0
 416          *
 417          * @return              An error code
 418          * @param[in]   key     The key for which the associated value needs to replace
 419          * @param[in]   value   The value associated with the key
 420          * @param[in]   pNewValue       The pointer to new value
 421          * @exception   E_SUCCESS               The method is successful.
 422          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 423          *                                                              the comparer has failed to compare the keys.
 424          * @exception   E_OBJ_NOT_FOUND The key-value pair is not found in the map.
 425          * @remarks             Use the Add() method to add a new key-value pair.
 426          * @see                 Add()
 427          * @see                 GetValuesN()
 428          */
 429         virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
 430
 431         /**
 432          * @if OSPDEPREC
 433          * Checks whether the map contains the specified key-value pair.
 434          *
 435          * @brief               <i> [Deprecated] </i>
 436          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 437          *                              The return type will be changed into boolean type and this method will return the result.
 438          *                              Instead of using this method, use bool Contains(const Object& key, const Object& value).
 439          * @since 2.0
 440          *
 441          * @return              An error code
 442          * @param[in]   key     The key to locate
 443          * @param[in]   value   The value to locate
 444          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
 445          *                                              else @c false
 446          * @exception   E_SUCCESS               The method is successful.
 447          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 448          *                                                              the comparer has failed to compare the keys.
 449          * @see                 ContainsKey()
 450          * @see                 ContainsValue()
 451          * @endif
 452          */
 453         result Contains(const Object& key, const Object& value, bool& out) const
 454         {
 455                 out = Contains(key, value);
 456                 result r = GetLastResult();
 457                 return r;
 458         }
 459
 460         /**
 461          * Checks whether the map contains the specified key-value pair.
 462          *
 463          * @since 2.0
 464          *
 465          * @return              @c true if the map contains the specified key-value pair, @n
 466          *                              else @c false
 467          * @param[in]   key     The key to locate
 468          * @param[in]   value   The value to locate
 469          * @exception   E_SUCCESS               The method is successful.
 470          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 471          *                                                              the comparer has failed to compare the keys.
 472          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 473          * @see                 ContainsKey()
 474          * @see                 ContainsValue()
 475          */
 476         virtual bool Contains(const Object& key, const Object& value) const = 0;
 477
 478         /**
 479          * @if OSPDEPREC
 480          * Checks whether the map contains the specified key.
 481          *
 482          * @brief               <i> [Deprecated] </i>
 483          * @deprecated  This method is deprecated because it transfers a result of comparison in out-parameter form.
 484          *                              The return type will be changed into boolean type and this method will return the result.
 485          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 486          * @since 2.0
 487          *
 488          * @return              An error code
 489          * @param[in]   key     The key to locate
 490          * @param[out]  out             Set to @c true if the map contains the specified key, @n
 491          *                                              else @c false
 492          * @exception   E_SUCCESS               The method is successful.
 493          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 494          *                                                              the comparer has failed to compare the keys.
 495          * @see                 ContainsValue()
 496          * @see                 Contains()
 497          * @endif
 498          */
 499         result ContainsKey(const Object& key, bool& out) const
 500         {
 501                 out = ContainsKey(key);
 502                 result r = GetLastResult();
 503                 return r;
 504         }
 505
 506         /**
 507          * Checks whether the map contains the specified key.
 508          *
 509          * @since 2.0
 510          *
 511          * @return              @c true if the map contains the specified key, @n
 512          *                              else @c false
 513          * @param[in]   key     The key to locate
 514          * @exception   E_SUCCESS               The method is successful.
 515          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 516          *                                                              the comparer has failed to compare the keys.
 517          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 518          * @see                 ContainsValue()
 519          * @see                 Contains()
 520          */
 521         virtual bool ContainsKey(const Object& key) const = 0;
 522
 523         /**
 524          * Checks whether the map contains the specified value.
 525          *
 526          * @since 2.0
 527          *
 528          * @return              @c true if the map contains the specified value, @n
 529          *                              else @c false
 530          * @param[in]   value   The value to locate
 531          *
 532          * @see                 ContainsKey()
 533          * @see                 Contains()
 534          */
 535         virtual bool ContainsValue(const Object& value) const = 0;
 536
 537         /**
 538          * Gets an enumerator of the map.
 539          *
 540          * @since 2.0
 541          *
 542          * @return              An instance of the IMapEnumerator class for the map, @n
 543          *                              else @c null if an exception occurs
 544          * @exception   E_SUCCESS               The method is successful.
 545          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
 546          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
 547          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 548          * @see                 IEnumerator
 549          * @see                 IMapEnumerator
 550          */
 551         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 552
 553         /**
 554          * Gets the element deleter of the collection.
 555          *
 556          * @since 2.0
 557          *
 558          * @return              An function pointer to the existing element deleter
 559          */
 560         virtual DeleterFunctionType GetDeleter(void) const = 0;
 561
 562 protected:
 563         //
 564         // This method is for internal use only. Using this method can cause behavioral, security-related,
 565         // and consistency-related issues in the application.
 566         // This method is reserved and may change its name at any time without prior notice.
 567         //
 568         // @since 2.0
 569         //
 570         virtual void IMultiMap_Reserved1(void) { }
 571
 572
 573         //
 574         // This method is for internal use only. Using this method can cause behavioral, security-related,
 575         // and consistency-related issues in the application.
 576         // This method is reserved and may change its name at any time without prior notice.
 577         //
 578         // @since 2.0
 579         //
 580         virtual void IMultiMap_Reserved2(void) { }
 581
 582 private:
 583         /**
 584          * Sets the element deleter of the collection.
 585          *
 586          * @since 2.0
 587          *
 588          * @param[in]   deleter A function pointer to the element deleter to set
 589          */
 590         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 591
 592 }; // IMultiMap
 593
 594 }}} // Tizen::Base::Collection
 595
 596 #endif // _FBASE_COL_IMULTI_MAP_H_