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