inc/FBaseColIList.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                FBaseColIList.h
  19  * @brief               This is the header file for the %IList interface.
  20  *
  21  * This header file contains the declarations of the %IList interface.
  22  */
  23 #ifndef _FBASE_COL_ILIST_H_
  24 #define _FBASE_COL_ILIST_H_
  25
  26 #include <FBaseColIBidirectionalEnumerator.h>
  27 #include <FBaseColICollection.h>
  28 #include <FBaseColIComparer.h>
  29 #include <FBaseColTypes.h>
  30 #include <FBaseObject.h>
  31
  32 namespace Tizen { namespace Base { namespace Collection
  33 {
  34
  35 /**
  36  * @interface   IList
  37  * @brief               This interface represents a collection of objects that can be individually accessed by an index.
  38  *
  39  * @since 2.0
  40  *
  41  * The %IList interface represents a collection of objects that can be individually accessed by an index.
  42  *
  43  */
  44 class _OSP_EXPORT_ IList
  45         : public virtual ICollection
  46 {
  47 public:
  48         /**
  49          * This polymorphic destructor should be overridden if required. @n
  50          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  51          *
  52          * @since 2.0
  53          */
  54         virtual ~IList(void) {}
  55
  56         /**
  57          * @if OSPDEPREC
  58          * Adds the specified object to the list.
  59          *
  60          * @brief               <i> [Deprecated] </i>
  61          * @deprecated  This method is deprecated because it has a problem of constant reference argument.
  62          *                              Instead of using this method, use Add(Object* pObj).
  63          * @since 2.0
  64          *
  65          * @return              An error code
  66          * @param[in]   obj                             The object to add
  67          * @exception   E_SUCCESS               The method is successful.
  68          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
  69          * @remarks
  70          *                              - In a collection of contiguous elements, such as a list, the elements
  71          *                              that follow the insertion point move down to accommodate the new element. @n
  72          *                              If the collection is indexed, the indexes of the elements that are moved
  73          *                              are also updated. @n
  74          *                              This behavior does not apply to collections where
  75          *                              elements are conceptually grouped into buckets, such as a hashtable.
  76          *                              - This method performs a shallow copy. It adds just the pointer only and not the element itself.
  77          * @see Remove()
  78          * @endif
  79          */
  80         result Add(const Object& obj)
  81         {
  82                 return Add(const_cast< Object* >(&obj));
  83         }
  84
  85         /**
  86          * Adds the specified object to the list.
  87          *
  88          * @since 2.0
  89          *
  90          * @return              An error code
  91          * @param[in]   pObj                            A pointer to the object to add
  92          * @exception   E_SUCCESS                       The method is successful.
  93          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
  94          * @remarks
  95          *                              - In a collection of contiguous elements, such as a list, the elements
  96          *                              that follow the insertion point move down to accommodate the new element. @n
  97          *                              If the collection is indexed, the indexes of the elements that are moved
  98          *                              are also updated. @n
  99          *                              This behavior does not apply to collections where
 100          *                              elements are conceptually grouped into buckets, such as a hashtable.
 101          *                              - This method performs a shallow copy. It adds just the pointer only and not the element itself.
 102          * @see Remove()
 103          */
 104         virtual result Add(Object* pObj) = 0;
 105
 106         /**
 107          * Adds the elements of the specified @c collection to the end of the list.
 108          *
 109          * @since 2.0
 110          *
 111          * @return              An error code
 112          * @param[in]   collection                      The collection to add to the list
 113          * @exception   E_SUCCESS                       The method is successful.
 114          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 115          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 116          *                                                                      - The specified @c collection is modified during the operation of this method.
 117          * @remarks     This method performs a shallow copy. It adds just the pointer only and not the element itself.
 118          * @see                 RemoveItems()
 119          */
 120         virtual result AddItems(const ICollection& collection) = 0;
 121
 122         /**
 123          * Searches for an object in this list. @n
 124          * Gets the @c index of the object if found.
 125          *
 126          * @since 2.0
 127          *
 128          * @return              An error code
 129          * @param[in]   obj                                     The object to locate
 130          * @param[out]  index                           The index of the object
 131          * @exception   E_SUCCESS                       The method is successful.
 132          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 133          */
 134         virtual result IndexOf(const Object& obj, int& index) const = 0;
 135
 136         /**
 137          * @if OSPDEPREC
 138          * Inserts an object at the specified location in the list.
 139          *
 140          * @brief               <i> [Deprecated] </i>
 141          * @deprecated  This method is deprecated because it has a problem of constant reference argument.
 142          *                              Instead of using this method, use InsertAt(const Object* pObj, int index).
 143          * @since 2.0
 144          *
 145          * @return              An error code
 146          * @param[in]   obj                                             The object to insert
 147          * @param[in]   index                                   The index at which the object is inserted
 148          * @exception   E_SUCCESS                               The method is successful.
 149          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 150          *                                                                              - The specified @c index is outside the bounds of the data structure.
 151          *                                                                              - The specified @c index is greater than the number of elements in the list.
 152          *                                                                              - The specified @c index is less than @c 0.
 153          * @remarks
 154          *                              - If the @c index equals the number of elements in the list, the new element
 155          *                              is added at the end of the list.
 156          *                              - This method performs a shallow copy. It inserts just the pointer only and not the element itself.
 157          * @see                 Add(Object*)
 158          * @see                 RemoveAt()
 159          * @endif
 160          */
 161         result InsertAt(const Object& obj, int index)
 162         {
 163                 return InsertAt(const_cast< Object* >(&obj), index);
 164         }
 165
 166         /**
 167          * Inserts an object at the specified location in the list.
 168          *
 169          * @since 2.0
 170          *
 171          * @return              An error code
 172          * @param[in]   pObj                            A pointer to the object to insert
 173          * @param[in]   index                           The index at which the object is inserted
 174          * @exception   E_SUCCESS                       The method is successful.
 175          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 176          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 177          *                                                                      - The specified index is outside the bounds of the data structure.
 178          *                                                                      - The specified @c index is greater than the number of elements in the list.
 179          *                                                                      - The specified @c index is less than @c 0.
 180          * @remarks
 181          *                              - If the @c index equals the number of elements in the list, the new element
 182          *                              is added at the end of the list.
 183          *                              - This method performs a shallow copy. It inserts just the pointer only and not the element itself.
 184          * @see                 Add(Object*)
 185          * @see                 RemoveAt()
 186          */
 187         virtual result InsertAt(Object* pObj, int index) = 0;
 188
 189         /**
 190          * Searches for an object starting from the specified @c index. @n
 191          * Gets the @c index of the object if found.
 192          *
 193          * @since 2.0
 194          *
 195          * @return              An error code
 196          * @param[in]   obj                             The object to locate
 197          * @param[in]   startIndex                              The starting index for the search @n
 198          *                                                                              It must be less than the number of elements.
 199          * @param[out]  index                                   The index of the object
 200          * @exception   E_SUCCESS                               The method is successful.
 201          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 202          *                                                                              - The specified @c index is outside the bounds of the data structure.
 203          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 204          *                                                                              - The specified @c startIndex is less than @c 0.
 205          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
 206          * @see                 LastIndexOf()
 207          */
 208         virtual result IndexOf(const Object& obj, int startIndex, int& index) const = 0;
 209
 210         /**
 211          * Searches for an object within the specified range. @n
 212          * Gets the @c index of the object if found.
 213          *
 214          * @since 2.0
 215          *
 216          * @return              An error code
 217          * @param[in]   obj                                             The object to locate
 218          * @param[in]   startIndex                              The starting index of the range
 219          * @param[in]   count                                   The number of elements to read
 220          * @param[out]  index                                   The index of the object
 221          * @exception   E_SUCCESS                               The method is successful.
 222          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 223          *                                                                              - The specified @c index is outside the bounds of the data structure.
 224          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 225          *                                                                              - The specified @c startIndex is less than @c 0.
 226          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
 227          *                                                                              - The specified @c count is less than @c 0.
 228          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
 229          * @see                 LastIndexOf()
 230          */
 231         virtual result IndexOf(const Object& obj, int startIndex, int count, int& index) const = 0;
 232
 233         /**
 234          * Searches for the last occurrence of an object in the list. @n
 235          * Gets the @c index of the object if found.
 236          *
 237          * @since 2.0
 238          *
 239          * @return              An error code
 240          * @param[in]   obj                     The object to locate
 241          * @param[out]  index                           The index of the last occurrence of the specified object
 242          * @exception   E_SUCCESS                       The method is successful.
 243          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 244          * @see                 IndexOf()
 245          */
 246         virtual result LastIndexOf(const Object& obj, int& index) const = 0;
 247
 248         /**
 249          * Inserts the elements of a collection in the list at the specified location.
 250          *
 251          * @since 2.0
 252          *
 253          * @return              An error code
 254          * @param[in]   collection                              The collection to insert
 255          * @param[in]   startIndex                              The starting index at which the collection is inserted
 256          * @exception   E_SUCCESS                               The method is successful.
 257          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 258          *                                                                              - The specified @c index is outside the bounds of the data structure.
 259          *                                                                              - The specified @c startIndex is greater than the number of elements in the list.
 260          *                                                                              - The specified @c startIndex is less than @c 0.
 261          * @exception   E_INVALID_OPERATION             Either of the following conditions has occurred:
 262          *                                                                              - The current state of the instance prohibits the execution of the specified operation.
 263          *                                                                              - The specified @c collection is modified during the operation of this method.
 264          * @remarks
 265          *                              - If the @c startIndex is equal to the number of elements in the list, the new elements
 266          *                              are added at the end of the list.
 267          *                              - This method performs a shallow copy. It inserts just the pointer and not the element itself.
 268          * @see                 RemoveItems()
 269          * @see                 AddItems()
 270          */
 271         virtual result InsertItemsFrom(const ICollection& collection, int startIndex) = 0;
 272
 273         /**
 274          * Gets the object at the specified location.
 275          *
 276          * @since 2.0
 277          *
 278          * @return              The object at the specified location, @n
 279          *                              else @c null if the @c index invalid
 280          * @param[in]   index                                   The index of the object to get
 281          * @exception   E_SUCCESS                               The method is successful.
 282          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 283          *                                                                              - The specified @c index is outside the bounds of the data structure.
 284          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 285          *                                                                              - The specified @c index is less than @c 0.
 286          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 287          * @see                 SetAt()
 288          */
 289         virtual const Object* GetAt(int index) const = 0;
 290
 291         /**
 292          * Gets the object at the specified location.
 293          *
 294          * @since 2.0
 295          *
 296          * @return              The object at the specified location, @n
 297          *                              else @c null if the @c index invalid
 298          * @param[in]   index                                   The index of the object to get
 299          * @exception   E_SUCCESS                               The method is successful.
 300          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 301          *                                                                              - The specified @c index is outside the bounds of the data structure.
 302          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 303          *                                                                              - The specified @c index is less than @c 0.
 304          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 305          * @see                 SetAt()
 306          */
 307         virtual Object* GetAt(int index) = 0;
 308
 309         /**
 310          * Gets all the elements of the list within the specified range.
 311          *
 312          * @since 2.0
 313          *
 314          * @return              A pointer to the %IList that contains elements lying within the specified range, @n
 315          *                              else @c null if an exception occurs
 316          * @param[in]   startIndex                              The starting index of the range
 317          * @param[in]   count                                   The number of elements to read
 318          * @exception   E_SUCCESS                               The method is successful.
 319          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 320          *                                                                              - The specified @c index is outside the bounds of the data structure.
 321          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 322          *                                                                              - The specified @c startIndex is less than @c 0.
 323          *                                                                              - The specified @c count is greater than the number of elements in the list starting from @c startIndex.
 324          *                                                                              - The specified @c count is less than @c 0.
 325          * @remarks
 326          *                              - The %IList stores just the pointers to the elements in the list and not the elements themselves.
 327          *                              - The specific error code can be accessed using the GetLastResult() method.
 328          */
 329         virtual IList* GetItemsN(int startIndex, int count) const = 0;
 330
 331         /**
 332          * Removes the first occurrence of the specified object.
 333          *
 334          * @since 2.0
 335          *
 336          * @return              An error code
 337          * @param[in]   obj                                     The object to remove
 338          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 339          *                                                                      else @c false
 340          * @exception   E_SUCCESS                       The method is successful.
 341          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 342          * @remarks
 343          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 344          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 345          *                              If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
 346          *                              - Remove(obj, @b true) internally works as the below code:
 347          * @code
 348          * DeleterFunctionType deleter = GetDeleter();
 349          * SetDeleter(SingleObjectDeleter);
 350          * Remove(obj);
 351          * SetDeleter(deleter);
 352          * @endcode
 353          *                              - Remove(obj, @b false) internally works as the below code:
 354          * @code
 355          * DeleterFunctionType deleter = GetDeleter();
 356          * SetDeleter(NoOpDeleter);
 357          * Remove(obj);
 358          * SetDeleter(deleter);
 359          * @endcode
 360          * @see                 Add(Object*)
 361          * @see                 RemoveAt()
 362          */
 363         result Remove(const Object& obj, bool forceDeletion)
 364         {
 365                 DeleterFunctionType deleter = GetDeleter();
 366
 367                 if (forceDeletion)
 368                 {
 369                         SetDeleter(SingleObjectDeleter);
 370                 }
 371                 else
 372                 {
 373                         SetDeleter(NoOpDeleter);
 374                 }
 375
 376                 result r = Remove(obj);
 377                 SetDeleter(deleter);
 378                 return r;
 379         }
 380
 381         /**
 382          * Removes the first occurrence of the specified object.
 383          *
 384          * @since 2.0
 385          *
 386          * @return              An error code
 387          * @param[in]   obj                                     The object to remove
 388          * @exception   E_SUCCESS                       The method is successful.
 389          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 390          * @see                 Add(Object*)
 391          * @see                 RemoveAt()
 392          */
 393         virtual result Remove(const Object& obj) = 0;
 394
 395         /**
 396          * Removes the object at the specified location.
 397          *
 398          * @since 2.0
 399          *
 400          * @return              An error code
 401          * @param[in]   index                                   The index at which the object is removed
 402          * @param[in]   forceDeletion                   Set to @c true to deallocate the object, @n
 403          *                                                                              else @c false
 404          * @exception   E_SUCCESS                               The method is successful.
 405          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 406          *                                                                              - The specified @c index is outside the bounds of the data structure.
 407          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 408         *                                                                               - The specified @c index is less than @c 0.
 409          * @remarks
 410          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 411          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 412          *                              If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
 413          *                              - RemoveAt(index, @b true) internally works as the below code:
 414          * @code
 415          * DeleterFunctionType deleter = GetDeleter();
 416          * SetDeleter(SingleObjectDeleter);
 417          * RemoveAt(index);
 418          * SetDeleter(deleter);
 419          * @endcode
 420          *                              - RemoveAt(index, @b false) internally works as the below code:
 421          * @code
 422          * DeleterFunctionType deleter = GetDeleter();
 423          * SetDeleter(NoOpDeleter);
 424          * RemoveAt(index);
 425          * SetDeleter(deleter);
 426          * @endcode
 427          */
 428         result RemoveAt(int index, bool forceDeletion)
 429         {
 430                 DeleterFunctionType deleter = GetDeleter();
 431
 432                 if (forceDeletion)
 433                 {
 434                         SetDeleter(SingleObjectDeleter);
 435                 }
 436                 else
 437                 {
 438                         SetDeleter(NoOpDeleter);
 439                 }
 440
 441                 result r = RemoveAt(index);
 442                 SetDeleter(deleter);
 443                 return r;
 444         }
 445
 446         /**
 447          * Removes the object at the specified location.
 448          *
 449          * @since 2.0
 450          *
 451          * @return              An error code
 452          * @param[in]   index                                   The index at which the object is removed
 453          * @exception   E_SUCCESS                               The method is successful.
 454          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 455          *                                                                              - The specified index is outside the bounds of the data structure.
 456          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 457          *                                                                              - The specified @c index is less than @c 0.
 458          */
 459         virtual result RemoveAt(int index) = 0;
 460
 461         /**
 462          * Removes all the elements within the specified range.
 463          *
 464          * @since 2.0
 465          *
 466          * @return              An error code
 467          * @param[in]   startIndex                              The starting index of the range
 468          * @param[in]   count                                   The number of elements in the range
 469          * @param[in]   forceDeletion                   Set to @c true to deallocate the object, @n
 470          *                                                                              else @c false
 471          * @exception   E_SUCCESS                               The method is successful.
 472          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 473          *                                                                              - The specified @c index is outside the bounds of the data structure.
 474          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 475          *                                                                              - The specified @c startIndex is less than @c 0.
 476          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
 477          *                                                                              - The specified @c count is less than @c 0.
 478          * @remarks
 479          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 480          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 481          *                              If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
 482          *                              - RemoveItems(startIndex, count, @b true) internally works as the below code:
 483          * @code
 484          * DeleterFunctionType deleter = GetDeleter();
 485          * SetDeleter(SingleObjectDeleter);
 486          * RemoveItems(startIndex, count);
 487          * SetDeleter(deleter);
 488          * @endcode
 489          *                              - RemoveItems(startIndex, count, @b false) internally works as the below code:
 490          * @code
 491          * DeleterFunctionType deleter = GetDeleter();
 492          * SetDeleter(NoOpDeleter);
 493          * RemoveItems(startIndex, count);
 494          * SetDeleter(deleter);
 495          * @endcode
 496          * @see                 AddItems()
 497          */
 498         result RemoveItems(int startIndex, int count, bool forceDeletion)
 499         {
 500                 DeleterFunctionType deleter = GetDeleter();
 501
 502                 if (forceDeletion)
 503                 {
 504                         SetDeleter(SingleObjectDeleter);
 505                 }
 506                 else
 507                 {
 508                         SetDeleter(NoOpDeleter);
 509                 }
 510
 511                 result r = RemoveItems(startIndex, count);
 512                 SetDeleter(deleter);
 513                 return r;
 514         }
 515
 516         /**
 517          * Removes all the elements within the specified range.
 518          *
 519          * @since 2.0
 520          *
 521          * @return              An error code
 522          * @param[in]   startIndex                              The starting index of the range
 523          * @param[in]   count                                   The number of elements in the range
 524          * @exception   E_SUCCESS                               The method is successful.
 525          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 526          *                                                                              - The specified @c index is outside the bounds of the data structure.
 527          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 528          *                                                                              - The specified @c startIndex is less than @c 0.
 529          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
 530          *                                                                              - The specified @c count is less than @c 0.
 531          * @see                 AddItems()
 532          */
 533         virtual result RemoveItems(int startIndex, int count) = 0;
 534
 535         /**
 536          * Removes all the elements from the list that are common to the specified collection.
 537          *
 538          * @since 2.0
 539          *
 540          * @return              An error code
 541          * @param[in]   collection                      The collection to remove from this list
 542          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 543          *                                                                      else @c false
 544          * @exception   E_SUCCESS                       The method is successful.
 545          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 546          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 547          *                                                                      - The specified @c collection is modified during the operation of this method.
 548          * @remarks
 549          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 550          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 551          *                              If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
 552          *                              - RemoveItems(collection, @b true) internally works as the below code:
 553          * @code
 554          * DeleterFunctionType deleter = GetDeleter();
 555          * SetDeleter(SingleObjectDeleter);
 556          * RemoveItems(collection);
 557          * SetDeleter(deleter);
 558          * @endcode
 559          *                              - RemoveItems(collection, @b false) internally works as the below code:
 560          * @code
 561          * DeleterFunctionType deleter = GetDeleter();
 562          * SetDeleter(NoOpDeleter);
 563          * RemoveItems(collection);
 564          * SetDeleter(deleter);
 565          * @endcode
 566          * @see                 Remove()
 567          * @see                 RemoveAt()
 568          */
 569         result RemoveItems(const ICollection& collection, bool forceDeletion)
 570         {
 571                 DeleterFunctionType deleter = GetDeleter();
 572
 573                 if (forceDeletion)
 574                 {
 575                         SetDeleter(SingleObjectDeleter);
 576                 }
 577                 else
 578                 {
 579                         SetDeleter(NoOpDeleter);
 580                 }
 581
 582                 result r = RemoveItems(collection);
 583                 SetDeleter(deleter);
 584                 return r;
 585         }
 586
 587         /**
 588          * Removes all the elements from the list that are common to the specified @c collection.
 589          *
 590          * @since 2.0
 591          *
 592          * @return              An error code
 593          * @param[in]   collection                      The collection to remove from this list
 594          * @exception   E_SUCCESS                       The method is successful.
 595          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 596          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 597          *                                                                      - The specified @c collection is modified during the operation of this method.
 598          * @see                 Remove()
 599          * @see                 RemoveAt()
 600          */
 601         virtual result RemoveItems(const ICollection& collection) = 0;
 602
 603         /**
 604          * Removes all the object pointers in the collection. @n
 605          * If @c forceDeletion is set to @c true, it removes all the objects from the collection. @n
 606          * This method can be called just before deleting the collection.
 607          *
 608          * @since 2.0
 609          *
 610          * @return              An error code
 611          * @param[in]   forceDeletion           Set to @c true to deallocate all the objects, @n
 612          *                                                                      else @c false
 613          * @remarks
 614          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 615          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 616          *                              If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
 617          *                              - RemoveAll(@b true) internally works as the below code:
 618          * @code
 619          * DeleterFunctionType deleter = GetDeleter();
 620          * SetDeleter(SingleObjectDeleter);
 621          * RemoveAll();
 622          * SetDeleter(deleter);
 623          * @endcode
 624          *                              - RemoveAll(@b false) internally works as the below code:
 625          * @code
 626          * DeleterFunctionType deleter = GetDeleter();
 627          * SetDeleter(NoOpDeleter);
 628          * RemoveAll();
 629          * SetDeleter(deleter);
 630          * @endcode
 631          */
 632         void RemoveAll(bool forceDeletion)
 633         {
 634                 DeleterFunctionType deleter = GetDeleter();
 635
 636                 if (forceDeletion)
 637                 {
 638                         SetDeleter(SingleObjectDeleter);
 639                 }
 640                 else
 641                 {
 642                         SetDeleter(NoOpDeleter);
 643                 }
 644
 645                 RemoveAll();
 646                 SetDeleter(deleter);
 647         }
 648
 649         /**
 650          * Removes all the object pointers from the collection. @n
 651          * This method can be called just before deleting the collection.
 652          *
 653          * @since 2.0
 654          */
 655         virtual void RemoveAll(void) = 0;
 656
 657         /**
 658          * Replaces the object at the specified @c index with the specified object.
 659          *
 660          * @since 2.0
 661          *
 662          * @return              An error code
 663          * @param[in]   obj                                     The new object
 664          * @param[in]   index                                   The index at which the new object is set
 665          * @param[in]   forceDeletion                   Set to @c true to deallocate the object, @n
 666          *                                                                              else @c false
 667          * @exception   E_SUCCESS                               The method is successful.
 668          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 669          *                                                                              - The specified @c index is outside the bounds of the data structure.
 670          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 671          *                                                                              - The specified @c index is less than @c 0.
 672          * @remarks
 673          *                              - Based on the specified element deleter, the set operation not only gets rid of an element from the list, but also deletes its object instance. @n
 674          *                              The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n
 675          *                              If both the element deleter and the @c forceDeleteion are set, the set operation follows the @c forceDeletion setting.
 676          *                              - SetAt(obj, index, @b true) internally works as the below code:
 677          * @code
 678          * DeleterFunctionType deleter = GetDeleter();
 679          * SetDeleter(SingleObjectDeleter);
 680          * SetAt(const_cast< Object* >(&obj), index);
 681          * SetDeleter(deleter);
 682          * @endcode
 683          *                              - SetAt(obj, index, @b false) internally works as the below code:
 684          * @code
 685          * DeleterFunctionType deleter = GetDeleter();
 686          * SetDeleter(NoOpDeleter);
 687          * SetAt(const_cast< Object* >(&obj), index);
 688          * SetDeleter(deleter);
 689          * @endcode
 690          * @see                 GetAt()
 691          */
 692         result SetAt(const Object& obj, int index, bool forceDeletion = false)
 693         {
 694                 DeleterFunctionType deleter = GetDeleter();
 695
 696                 if (forceDeletion)
 697                 {
 698                         SetDeleter(SingleObjectDeleter);
 699                 }
 700                 else
 701                 {
 702                         SetDeleter(NoOpDeleter);
 703                 }
 704
 705                 result r = SetAt(const_cast< Object* >(&obj), index);
 706                 SetDeleter(deleter);
 707                 return r;
 708         }
 709
 710         /**
 711          * Replaces the object at the specified @c index with the specified object.
 712          *
 713          * @since 2.0
 714          *
 715          * @return              An error code
 716          * @param[in]   pObj                                    A pointer to the new object
 717          * @param[in]   index                                   The index at which the new object is set
 718          * @exception   E_SUCCESS                               The method is successful.
 719          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 720          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 721          *                                                                              - The specified index is outside the bounds of the data structure.
 722          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 723          *                                                                              - The specified @c index is less than @c 0.
 724          * @see                 GetAt()
 725          */
 726         virtual result SetAt(Object* pObj, int index) = 0;
 727
 728         /**
 729          * Sorts the elements of the list using the @c comparer provided.
 730          *
 731          * @since 2.0
 732          *
 733          * @return              An error code
 734          * @param[in]   comparer                The IComparer implementation to use when comparing the elements
 735          * @exception   E_SUCCESS               The method is successful.
 736          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 737          */
 738         virtual result Sort(const IComparer& comparer) = 0;
 739
 740         /**
 741          * Checks whether the list contains the specified object.
 742          *
 743          * @since 2.0
 744          *
 745          * @return              @c true if the list contains the specified object, @n
 746          *                              else @c false
 747          * @param[in]   obj     The object to locate
 748          */
 749         virtual bool Contains(const Object& obj) const = 0;
 750
 751         /**
 752          * @if OSPDEPREC
 753          * Checks whether the list contains all the elements of the specified @c collection.
 754          *
 755          * @brief               <i> [Deprecated] </i>
 756          * @deprecated  This method is deprecated because it transfers the result of the comparison in an out-parameter form.
 757          *                              The return type is changed to boolean and this method returns the result.
 758          *                              Instead of using this method, use bool ContainsAll(const ICollection& collection).
 759          * @since 2.0
 760          *
 761          * @return              An error code
 762          * @param[in]   collection                      The collection to check for containment in this list
 763          * @param[out]  out                                     Set to @c true if the list contains all the elements of the specified collection, @n
 764          *                                                                      else @c false
 765          * @exception   E_SUCCESS                       The method is successful.
 766          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 767          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 768          *                                                                      - The specified @c collection is modified during the operation of this method.
 769          * @remarks             If the given @c collection is empty, then @c out is set to @c true.
 770          * @see                 Contains()
 771          * @endif
 772          */
 773         result ContainsAll(const ICollection& collection, bool& out) const
 774         {
 775                 out = ContainsAll(collection);
 776                 result r = GetLastResult();
 777                 return r;
 778         }
 779
 780         /**
 781          * Checks whether the list contains all the elements of the specified @c collection.
 782          *
 783          * @since 2.0
 784          *
 785          * @return              @c true if the list contains all the elements of the specified collection, @n
 786          *                              else @c false
 787          * @param[in]   collection                      The collection to check for containment in this list
 788          * @exception   E_SUCCESS                       The method is successful.
 789          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 790          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 791          *                                                                      - The specified @c collection is modified during the operation of this method.
 792          * @remarks
 793          *                              - The specific error code can be accessed using the GetLastResult() method.
 794          *                              - If the given @c collection is empty, this method returns @c true.
 795          * @see                 Contains()
 796          */
 797         virtual bool ContainsAll(const ICollection& collection) const = 0;
 798
 799         /**
 800         * Gets the bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class) of this list.
 801         *
 802         * @since 2.0
 803         *
 804         * @return               A pointer to the bidirectional enumerator interface of the %IList derived class, @n
 805         *                               else @c null if an exception occurs
 806         * @remarks
 807         *                               - Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumerator derived class)
 808         *                               to iterate over a collection (an instance of the %IList derived class).
 809         *                               - The specific error code can be accessed using GetLastResult() method.
 810         */
 811         virtual IBidirectionalEnumerator* GetBidirectionalEnumeratorN(void) const = 0;
 812
 813         /**
 814          * Checks whether the instance is an ArrayList or a LinkedList.
 815          *
 816          * @since 2.0
 817          *
 818          * @return      @c true if it is an ArrayList, @n
 819          *                      else @c false if it is a LinkedList
 820          */
 821         virtual bool IsRandomAccessible(void) const
 822         {
 823                 return false;
 824         }
 825
 826         /**
 827          * Gets the element deleter of the collection.
 828          *
 829          * @since 2.0
 830          *
 831          * @return              A function pointer to the existing element deleter
 832          */
 833         virtual DeleterFunctionType GetDeleter(void) const = 0;
 834
 835 protected:
 836         //
 837         // This method is for internal use only. Using this method can cause behavioral, security-related,
 838         // and consistency-related issues in the application.
 839         // This method is reserved and may change its name at any time without prior notice.
 840         //
 841         // @since 2.0
 842         //
 843         virtual void IList_Reserved1(void) {}
 844
 845         //
 846         // This method is for internal use only. Using this method can cause behavioral, security-related,
 847         // and consistency-related issues in the application.
 848         // This method is reserved and may change its name at any time without prior notice.
 849         //
 850         // @since 2.0
 851         //
 852         virtual void IList_Reserved2(void) {}
 853
 854 private:
 855         /**
 856          * Sets the element deleter of the collection.
 857          *
 858          * @since 2.0
 859          *
 860          * @param[in]   deleter A function pointer to the element deleter to set
 861          */
 862         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 863
 864 }; // IList
 865
 866 }}} // Tizen::Base::Collection
 867
 868 #endif // _FBASE_COL_ILIST_H_