inc/FBaseColIListT.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                FBaseColIListT.h
  19  * @brief               This is the header file for the %IListT interface.
  20  *
  21  * This header file contains the declarations of the %IListT interface.
  22  */
  23 #ifndef _FBASE_COL_ILIST_T_H_
  24 #define _FBASE_COL_ILIST_T_H_
  25
  26 #include <FBaseColIBidirectionalEnumeratorT.h>
  27 #include <FBaseColICollectionT.h>
  28 #include <FBaseColIComparerT.h>
  29
  30 namespace Tizen { namespace Base { namespace Collection
  31 {
  32
  33 /**
  34  * @interface   IListT
  35  * @brief               This interface represents a template-based collection of objects that can be individually accessed by an index.
  36  *
  37  * @since 2.0
  38  *
  39  * The %IListT interface represents a template-based collection of objects that can be individually accessed by an index.
  40  *
  41  */
  42 template< class Type >
  43 class IListT
  44         : public virtual ICollectionT< Type >
  45 {
  46 public:
  47         /**
  48          * This polymorphic destructor should be overridden if required. @n
  49          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  50          *
  51          * @since 2.0
  52          */
  53         virtual ~IListT(void) {}
  54
  55         /**
  56          * Adds the specified object to the list.
  57          *
  58          * @since 2.0
  59          *
  60          * @return              An error code
  61          * @param[in]   obj                             The object to add
  62          * @exception   E_SUCCESS               The method is successful.
  63          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
  64          * @remarks             In a collection of contiguous elements, such as a list, the elements
  65          *                              that follow the insertion point move down to accommodate the new element.
  66          *                              If the collection is indexed, the indexes of the elements that are moved
  67          *                              are also updated. This behavior does not apply to collections where
  68          *                              elements are conceptually grouped into buckets, such as a hashtable.
  69          * @see Remove()
  70          */
  71         virtual result Add(const Type& obj) = 0;
  72
  73         /**
  74          * Adds the elements of the specified collection to the end of the list.
  75          *
  76          * @since 2.0
  77          *
  78          * @return              An error code
  79          * @param[in]   collection                      The collection to add
  80          * @exception   E_SUCCESS                       The method is successful.
  81          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
  82          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
  83          *                                                                      - The specified @c collection is modified during the operation of this method.
  84          * @see                 RemoveItems()
  85          */
  86         virtual result AddItems(const ICollectionT< Type >& collection) = 0;
  87
  88         /**
  89          * Searches for an object in this list. @n
  90          * Gets the @c index of the object if found.
  91          *
  92          * @since 2.0
  93          *
  94          * @return              An error code
  95          * @param[in]   obj                                     The object to locate
  96          * @param[out]  index                           The index of the object
  97          * @exception   E_SUCCESS                       The method is successful.
  98          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
  99          */
 100         virtual result IndexOf(const Type& obj, int& index) const = 0;
 101
 102         /**
 103          * Searches for an object starting from the specified @c startIndex. @n
 104          * Gets the @c index of the object if found.
 105          *
 106          * @since 2.0
 107          *
 108          * @return              An error code
 109          * @param[in]   obj                             The object to locate
 110          * @param[in]   startIndex                              The starting index for the search @n
 111          *                                                                              It must be less than the number of elements.
 112          * @param[out]  index                                   The index of the object
 113          * @exception   E_SUCCESS                               The method is successful.
 114          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 115          *                                                                              - The specified @c index is outside the bounds of the data structure.
 116          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 117          *                                                                              - The specified @c startIndex is less than @c 0.
 118          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
 119          * @see                 LastIndexOf()
 120          */
 121         virtual result IndexOf(const Type& obj, int startIndex, int& index) const = 0;
 122
 123         /**
 124          * Searches for an object within the specified range. @n
 125          * Gets the @c index of the object if found.
 126          *
 127          * @since 2.0
 128          *
 129          * @return              An error code
 130          * @param[in]   obj                             The object to locate
 131          * @param[in]   startIndex                              The starting index of the range
 132          * @param[in]   count                                   The number of elements to read
 133          * @param[out]  index                                   The index of the object
 134          * @exception   E_SUCCESS                               The method is successful.
 135          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 136          *                                                                              - The specified @c index is outside the bounds of the data structure.
 137          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 138          *                                                                              - The specified @c startIndex is less than @c 0.
 139          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
 140          *                                                                              - The specified @c count is less than @c 0.
 141          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj has not been found.
 142          * @see                 LastIndexOf()
 143          */
 144         virtual result IndexOf(const Type& obj, int startIndex, int count, int& index) const = 0;
 145
 146         /**
 147          * Searches for the last occurrence of an object in this list. @n
 148          * Gets the @c index of the object if found.
 149          *
 150          * @since 2.0
 151          *
 152          * @return              An error code
 153          * @param[in]   obj                     The object to locate
 154          * @param[out]  index                           The index of the last occurrence of the specified object
 155          * @exception   E_SUCCESS                       The method is successful.
 156          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 157          * @see                 IndexOf()
 158          */
 159         virtual result LastIndexOf(const Type& obj, int& index) const = 0;
 160
 161         /**
 162          * Inserts an object at the specified location in the list.
 163          *
 164          * @since 2.0
 165          *
 166          * @return              An error code
 167          * @param[in]   obj                                             The object to insert
 168          * @param[in]   index                                   The index at which the object is inserted
 169          * @exception   E_SUCCESS                               The method is successful.
 170          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 171          *                                                                              - The specified @c index is outside the bounds of the data structure.
 172          *                                                                              - The specified @c index is greater than the number of elements in the list.
 173          *                                                                              - The specified @c index is less than @c 0.
 174          * @remarks             If the @c index is equal to the number of elements in the list, the new element
 175          *                              is added at the end of the list.
 176          * @see                 Add()
 177          * @see                 RemoveAt()
 178          */
 179         virtual result InsertAt(const Type& obj, int index) = 0;
 180
 181         /**
 182          * Inserts the elements of a collection at the specified location in the list.
 183          *
 184          * @since 2.0
 185          *
 186          * @return              An error code
 187          * @param[in]   collection                              The collection to insert
 188          * @param[in]   startIndex                              The starting index at which the collection is inserted
 189          * @exception   E_SUCCESS                               The method is successful.
 190          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 191          *                                                                              - The specified @c index is outside the bounds of the data structure.
 192          *                                                                              - The specified @c startIndex is greater than the number of elements in the list.
 193          *                                                                              - The specified @c startIndex is less than @c 0.
 194          * @exception   E_INVALID_OPERATION             Either of the following conditions has occurred:
 195          *                                                                              - The current state of the instance prohibits the execution of the specified operation.
 196          *                                                                              - The specified @c collection is modified during the operation of this method.
 197          * @remarks             If the @c startIndex equals the number of elements in the list, the new elements
 198          *                              are added at the end of the list.
 199          * @see                 RemoveItems()
 200          * @see                 AddItems()
 201          */
 202         virtual result InsertItemsFrom(const ICollectionT< Type >& collection, int startIndex) = 0;
 203
 204         /**
 205          * Gets the object at the specified location.
 206          *
 207          * @since 2.0
 208          *
 209          * @return              An error code
 210          * @param[in]   index                                   The index of the object to get
 211          * @param[out]  obj                                             The object obtained from the list
 212          * @exception   E_SUCCESS                               The method is successful.
 213          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 214          *                                                                              - The specified @c index is outside the bounds of the data structure.
 215          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 216          *                                                                              - The specified @c index is less than @c 0.
 217          * @see                 SetAt()
 218          */
 219         virtual result GetAt(int index, Type& obj) const = 0;
 220
 221         /**
 222          * Gets the object at the specified location.
 223          *
 224          * @since 2.0
 225          *
 226          * @return              An error code
 227          * @param[in]   index                                   The index of the object to get
 228          * @param[out]  obj                                             The object obtained from the list
 229          * @exception   E_SUCCESS                               The method is successful.
 230          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 231          *                                                                              - The specified @c index is outside the bounds of the data structure.
 232          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 233          *                                                                              - The specified @c index is less than @c 0.
 234          * @see                 SetAt()
 235          */
 236         virtual result GetAt(int index, Type& obj) = 0;
 237
 238         /**
 239          * Gets all the elements of the list within the specified range.
 240          *
 241          * @since 2.0
 242          *
 243          * @return              A pointer to %IListT that contains the elements lying within the specified range, @n
 244          *                              else @c null if an exception occurs
 245          * @param[in]   startIndex                              The starting index of the range
 246          * @param[in]   count                                   The number of elements to read
 247          * @exception   E_SUCCESS                               The method is successful.
 248          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 249          *                                                                              - The specified @c index is outside the bounds of the data structure.
 250          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 251          *                                                                              - The specified @c startIndex is less than @c 0.
 252          *                                                                              - The specified @c count is greater than the number of elements in the list starting from @c startIndex.
 253          *                                                                              - The specified @c count is less than @c 0.
 254          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 255          */
 256         virtual IListT< Type >* GetItemsN(int startIndex, int count) const = 0;
 257
 258         /**
 259          * Removes the first occurrence of the specified object.
 260          *
 261          * @since 2.0
 262          *
 263          * @return              An error code
 264          * @param[in]   obj                                     The object to remove
 265          * @exception   E_SUCCESS                       The method is successful.
 266          * @exception   E_OBJ_NOT_FOUND         The specified @c obj has not been found.
 267          */
 268         virtual result Remove(const Type& obj) = 0;
 269
 270         /**
 271          * Removes the object at the specified location.
 272          *
 273          * @since 2.0
 274          *
 275          * @return              An error code
 276          * @param[in]   index                                   The index at which the object is removed
 277          * @exception   E_SUCCESS                               The method is successful.
 278          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 279          *                                                                              - The specified @c index is outside the bounds of the data structure.
 280          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 281          *                                                                              - The specified @c index is less than @c 0.
 282          */
 283         virtual result RemoveAt(int index) = 0;
 284
 285         /**
 286          * Removes all the elements from the list that are common to the specified @c collection.
 287          *
 288          * @since 2.0
 289          *
 290          * @return              An error code
 291          * @param[in]   collection                      The collection to remove from this list
 292          * @exception   E_SUCCESS                       The method is successful.
 293          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 294          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 295          *                                                                      - The specified @c collection is modified during the operation of this method.
 296          * @see                 Remove()
 297          * @see                 RemoveAt()
 298          */
 299         virtual result RemoveItems(const ICollectionT< Type >& collection) = 0;
 300
 301         /**
 302          * Removes all the elements within the specified range.
 303          *
 304          * @since 2.0
 305          *
 306          * @return              An error code
 307          * @param[in]   startIndex                              The starting index of the range
 308          * @param[in]   count                                   The number of elements in the range
 309          * @exception   E_SUCCESS                               The method is successful.
 310          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 311          *                                                                              - The specified @c index is outside the bounds of the data structure.
 312          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements in the list.
 313          *                                                                              - The specified @c startIndex is less than @c 0.
 314          *                                                                              - The specified @c count is greater than the number of elements starting from @c startIndex.
 315          *                                                                              - The specified @c count is less than @c 0.
 316          * @see                 AddItems()
 317          * @see                 InsertItemsFrom()
 318          */
 319         virtual result RemoveItems(int startIndex, int count) = 0;
 320
 321         /**
 322          * Removes all the elements from the list.
 323          *
 324          * @since 2.0
 325          */
 326         virtual void RemoveAll(void) = 0;
 327
 328         /**
 329          * Sets the object at the specified @c index with the specified object.
 330          *
 331          * @since 2.0
 332          *
 333          * @return              An error code
 334          * @param[in]   obj                                             The new object
 335          * @param[in]   index                                   The index at which the new object is set
 336          * @exception   E_SUCCESS                               The method is successful.
 337          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 338          *                                                                              - The specified @c index is outside the bounds of the data structure.
 339          *                                                                              - The specified @c index is either greater than or equal to the number of elements in the list.
 340          *                                                                              - The specified @c index is less than @c 0.
 341          * @see                 GetAt()
 342          */
 343         virtual result SetAt(const Type& obj, int index) = 0;
 344
 345         /**
 346          * Sorts the elements of this list using the @c comparer provided.
 347          *
 348          * @since 2.0
 349          *
 350          * @return              An error code
 351          * @param[in]   comparer                The IComparerT implementation to use when comparing the elements
 352          * @exception   E_SUCCESS               The method is successful.
 353          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 354          */
 355         virtual result Sort(const IComparerT< Type >& comparer) = 0;
 356
 357         /**
 358          * Checks whether the list contains the specified object.
 359          *
 360          * @since 2.0
 361          *
 362          * @return              @c true if the list contains the specified object, @n
 363          *                              else @c false
 364          * @param[in]   obj     The object to locate
 365          */
 366         virtual bool Contains(const Type& obj) const = 0;
 367
 368         /**
 369          * Checks whether the list contains all the elements of the specified @c collection.
 370          *
 371          * @since 2.0
 372          *
 373          * @return              An error code
 374          * @param[in]   collection                      The collection to check for containment in this list
 375          * @param[out]  out                                     Set to @c true if the list contains all the elements of the specified collection, @n
 376          *                                                                      else @c false
 377          * @exception   E_SUCCESS                       The method is successful.
 378          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 379          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 380          *                                                                      - The specified @c collection is modified during the operation of this method.
 381          * @remarks             If the given @c collection is empty, then @c out is set to @c true.
 382          * @see                 Contains()
 383          */
 384         virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const = 0;
 385
 386         /**
 387          * Gets the bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class) of this list.
 388          *
 389          * @since 2.0
 390          *
 391          * @return              A pointer to the bidirectional enumerator interface of the %IListT derived class, @n
 392          *                              else @c null if an exception occurs
 393          * @exception   E_SUCCESS                       The method is successful.
 394          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 395          * @remarks
 396          *                              - Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class)
 397          *                              to iterate over a collection (an instance of the %IListT derived class).
 398          *                              - The specific error code can be accessed using the GetLastResult() method.
 399          */
 400         virtual IBidirectionalEnumeratorT< Type >* GetBidirectionalEnumeratorN(void) const = 0;
 401
 402 }; // IListT
 403
 404 }}} // Tizen::Base::Collection
 405
 406 #endif // _FBASE_COL_ILIST_T_H_