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     The current state of the instance prohibits the execution of the specified operation, or
  82          *                                                                      the specified @c collection is modified during the operation of this method.
  83          * @see                 RemoveItems()
  84          */
  85         virtual result AddItems(const ICollectionT< Type >& collection) = 0;
  86
  87         /**
  88          * Searches for an object in this list. @n
  89          * Gets the index of the object if found.
  90          *
  91          * @since 2.0
  92          *
  93          * @return              An error code
  94          * @param[in]   obj                     The object to locate
  95          * @param[out]  index           The index of the object
  96          * @exception   E_SUCCESS                       The method is successful.
  97          * @exception   E_OBJ_NOT_FOUND         The specified @c obj is not found.
  98          */
  99         virtual result IndexOf(const Type& obj, int& index) const = 0;
 100
 101         /**
 102          * Searches for an object starting from the specified index. @n
 103          * Gets the index of the object if found.
 104          *
 105          * @since 2.0
 106          *
 107          * @return              An error code
 108          * @param[in]   obj         The object to locate
 109          * @param[in]   startIndex      The starting index for the search @n
 110          *                                                      It must be less than the number of elements.
 111          * @param[out]  index           The index of the object
 112          * @exception   E_SUCCESS                               The method is successful.
 113          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 114          *                                                                              the specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0.
 115          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj is not found.
 116          * @see                 LastIndexOf()
 117          */
 118         virtual result IndexOf(const Type& obj, int startIndex, int& index) const = 0;
 119
 120         /**
 121          * Searches for an object within the specified range. @n
 122          * Gets the index of the object if found.
 123          *
 124          * @since 2.0
 125          *
 126          * @return              An error code
 127          * @param[in]   obj         The object to locate
 128          * @param[in]   startIndex      The starting index of the range
 129          * @param[in]   count           The number of elements to read
 130          * @param[out]  index           The index of the object
 131          * @exception   E_SUCCESS                               The method is successful.
 132          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred: @n
 133          *                                                                              - The specified index is outside the bounds of the data structure. @n
 134          *                                                                              - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
 135          *                                                                              - The @c count is greater than the number of elements starting from @c startIndex
 136          *                                                                              or less than @c 0.
 137          * @exception   E_OBJ_NOT_FOUND                 The specified @c obj is not found.
 138          * @see                 LastIndexOf()
 139          */
 140         virtual result IndexOf(const Type& obj, int startIndex, int count, int& index) const = 0;
 141
 142         /**
 143          * Searches for the last occurrence of an object in this list. @n
 144          * Gets the index of the object if found.
 145          *
 146          * @since 2.0
 147          *
 148          * @return              An error code
 149          * @param[in]   obj         The object to locate
 150          * @param[out]  index           The index of the last occurrence of the specified object
 151          * @exception   E_SUCCESS                       The method is successful.
 152          * @exception   E_OBJ_NOT_FOUND         The specified @c obj is not found.
 153          * @see                 IndexOf()
 154          */
 155         virtual result LastIndexOf(const Type& obj, int& index) const = 0;
 156
 157         /**
 158          * Inserts an object at the specified location in the list.
 159          *
 160          * @since 2.0
 161          *
 162          * @return              An error code
 163          * @param[in]   obj             The object to insert
 164          * @param[in]   index   The index at which the object must be inserted
 165          * @exception   E_SUCCESS                               The method is successful.
 166          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 167          *                                                                              the @c index is greater than the number of elements in the list or less than @c 0.
 168          * @remarks             If the @c index equals the number of elements in the list, the new element
 169          *                              is added at the end of the list.
 170          * @see                 Add()
 171          * @see                 RemoveAt()
 172          */
 173         virtual result InsertAt(const Type& obj, int index) = 0;
 174
 175         /**
 176          * Inserts the elements of a collection in the list at the specified location.
 177          *
 178          * @since 2.0
 179          *
 180          * @return              An error code
 181          * @param[in]   collection      The collection to insert
 182          * @param[in]   startIndex      The starting index at which the collection must be inserted
 183          * @exception   E_SUCCESS                               The method is successful.
 184          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 185          *                                                                              the @c startIndex is greater than the number of elements in the list or less than @c 0.
 186          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, or
 187          *                                                                              the specified @c collection is modified during the operation of this method.
 188          * @remarks             If the @c startIndex equals the number of elements in the list, the new elements
 189          *                              are added at the end of the list.
 190          * @see                 RemoveItems()
 191          * @see                 AddItems()
 192          */
 193         virtual result InsertItemsFrom(const ICollectionT< Type >& collection, int startIndex) = 0;
 194
 195         /**
 196          * Gets the object at the specified location.
 197          *
 198          * @since 2.0
 199          *
 200          * @return              An error code
 201          * @param[in]   index   The index of the object to get
 202          * @param[out]  obj             The object obtained from the list
 203          * @exception   E_SUCCESS                               The method is successful.
 204          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 205          *                                                                              the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
 206          * @see                 SetAt()
 207          */
 208         virtual result GetAt(int index, Type& obj) const = 0;
 209
 210         /**
 211          * Gets the object at the specified location.
 212          *
 213          * @since 2.0
 214          *
 215          * @return              An error code
 216          * @param[in]   index   The index of the object to get
 217          * @param[out]  obj             The object obtained from the list
 218          * @exception   E_SUCCESS                               The method is successful.
 219          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 220          *                                                                              the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
 221          * @see                 SetAt()
 222          */
 223         virtual result GetAt(int index, Type& obj) = 0;
 224
 225         /**
 226          * Gets all the elements of the list within the specified range.
 227          *
 228          * @since 2.0
 229          *
 230          * @return              A pointer to %IListT with elements lying within the specified range, @n
 231          *                              else @c null if an exception occurs
 232          * @param[in]   startIndex      The starting index of the range
 233          * @param[in]   count           The number of elements to read
 234          * @exception   E_SUCCESS                               The method is successful.
 235          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred: @n
 236          *                                                                              - The specified index is outside the bounds of the data structure. @n
 237          *                                                                              - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
 238          *                                                                              - The @c count is greater than the number of elements in the list starting from @c startIndex
 239          *                                                                              or less than @c 0.
 240          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 241          */
 242         virtual IListT< Type >* GetItemsN(int startIndex, int count) const = 0;
 243
 244         /**
 245          * Removes the first occurrence of the specified object.
 246          *
 247          * @since 2.0
 248          *
 249          * @return              An error code
 250          * @param[in]   obj                                     The object to remove
 251          * @exception   E_SUCCESS                       The method is successful.
 252          * @exception   E_OBJ_NOT_FOUND         The object is not found.
 253          */
 254         virtual result Remove(const Type& obj) = 0;
 255
 256         /**
 257          * Removes the object at the specified location.
 258          *
 259          * @since 2.0
 260          *
 261          * @return              An error code
 262          * @param[in]   index                                   The index at which the object must be removed
 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          */
 267         virtual result RemoveAt(int index) = 0;
 268
 269         /**
 270          * Removes all the elements from the list that are common to the specified collection.
 271          *
 272          * @since 2.0
 273          *
 274          * @return              An error code
 275          * @param[in]   collection                      The collection to remove from this list
 276          * @exception   E_SUCCESS                       The method is successful.
 277          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 278          *                                                                      the specified @c collection is modified during the operation of this method.
 279          * @see                 Remove()
 280          * @see                 RemoveAt()
 281          */
 282         virtual result RemoveItems(const ICollectionT< Type >& collection) = 0;
 283
 284         /**
 285          * Removes all the elements within the specified range.
 286          *
 287          * @since 2.0
 288          *
 289          * @return              An error code
 290          * @param[in]   startIndex      The starting index of the range
 291          * @param[in]   count           The number of elements in the range
 292          * @exception   E_SUCCESS                               The method is successful.
 293          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred: @n
 294          *                                                                              - The specified index is outside the bounds of the data structure. @n
 295          *                                                                              - The specified @c startIndex is either equal to or greater than the number of elements in the list or less than @c 0. @n
 296          *                                                                              - The @c count is greater than the number of elements starting from @c startIndex
 297          *                                                                              or less than @c 0.
 298          * @see                 AddItems()
 299          * @see                 InsertItemsFrom()
 300          */
 301         virtual result RemoveItems(int startIndex, int count) = 0;
 302
 303         /**
 304          * Removes all the elements in the list.
 305          *
 306          * @since 2.0
 307          */
 308         virtual void RemoveAll(void) = 0;
 309
 310         /**
 311          * Sets the object at the specified index with the specified object.
 312          *
 313          * @since 2.0
 314          *
 315          * @return              An error code
 316          * @param[in]   obj             The new object
 317          * @param[in]   index   The index at which the new object must be set
 318          * @exception   E_SUCCESS                               The method is successful.
 319          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure, or
 320          *                                                                              the specified @c index is either equal to or greater than the number of elements in the list or less than @c 0.
 321          * @see                 GetAt()
 322          */
 323         virtual result SetAt(const Type& obj, int index) = 0;
 324
 325         /**
 326          * Sorts the elements of this list using the comparer provided.
 327          *
 328          * @since 2.0
 329          *
 330          * @return              An error code
 331          * @param[in]   comparer                The IComparerT implementation to use when comparing elements
 332          * @exception   E_SUCCESS               The method is successful.
 333          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 334          */
 335         virtual result Sort(const IComparerT< Type >& comparer) = 0;
 336
 337         /**
 338          * Checks whether the list contains the specified object.
 339          *
 340          * @since 2.0
 341          *
 342          * @return              @c true if the list contains the specified object, @n
 343          *                              else @c false
 344          * @param[in]   obj     The object to locate
 345          */
 346         virtual bool Contains(const Type& obj) const = 0;
 347
 348         /**
 349          * Checks whether the list contains all the elements of the specified collection.
 350          *
 351          * @since 2.0
 352          *
 353          * @return              An error code
 354          * @param[in]   collection      The collection to check for containment in this list
 355          * @param[out]  out                     Set to @c true if the list contains all the elements of the specified collection, @n
 356          *                                                      else @c false
 357          * @exception   E_SUCCESS                       The method is successful.
 358          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 359          *                                                                      the specified @c collection is modified during the operation of this method.
 360          * @remarks             If the given @c collection is empty, the @c out parameter is set to @c true.
 361          * @see                 Contains()
 362          */
 363         virtual result ContainsAll(const ICollectionT< Type >& collection, bool& out) const = 0;
 364
 365         /**
 366          * Gets a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class) of this list.
 367          *
 368          * @since 2.0
 369          *
 370          * @return              A pointer to a bidirectional enumerator interface of the %IListT derived class, @n
 371          *                              else @c null if an exception occurs
 372          * @exception   E_SUCCESS                       The method is successful.
 373          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 374          * @remarks             Use this method to obtain a bidirectional enumerator (an instance of the IBidirectionalEnumeratorT derived class)
 375          *                              to iterate over a collection (an instance of the %IListT derived class).
 376          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 377          * @see                 Tizen::Base::Collection::IBidirectionalEnumeratorT
 378          */
 379         virtual IBidirectionalEnumeratorT< Type >* GetBidirectionalEnumeratorN(void) const = 0;
 380
 381 }; // IListT
 382
 383 }}} // Tizen::Base::Collection
 384
 385 #endif // _FBASE_COL_ILIST_T_H_