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