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