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