inc/FBaseColIList.h

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