inc/FBaseColRandomIteratorT.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2013 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                FBaseColRandomIteratorT.h
  20  * @brief               This is the header file for the %RandomIteratorT class.
  21  *
  22  * This header file contains the declarations of the %RandomIteratorT class.
  23  */
  24
  25 #ifndef _FBASE_COL_RANDOM_ITERATOR_T_H_
  26 #define _FBASE_COL_RANDOM_ITERATOR_T_H_
  27
  28 #include <algorithm>    // std::swap (Before C++11)
  29 #include <iterator>
  30 #include <FBaseColIList.h>
  31 #include <FBaseLog.h>
  32 #include <FBaseObject.h>
  33
  34 namespace Tizen { namespace Base { namespace Collection
  35 {
  36 /**
  37  * @class       RandomIteratorT
  38  * @brief       This class provides an random iterator that is used to convert IList to STL containers.
  39  *                      StlConverter provides static methods to get this random iterator from IList.
  40  *
  41  * @since       2.1
  42  *
  43  * @remarks     The %RandomIteratorT class satisfies only requirements of C++ standard library InputIterator concept due to limitations of %Tizen Collection.
  44  *                      So, this class can be used with C++ standard library algorithms which requires only InputIterator concept for their arguments.
  45  */
  46
  47 template < typename T >
  48 class RandomIteratorT
  49         : public std::iterator< std::input_iterator_tag, T >
  50 {
  51 public:
  52         /**
  53          * Initializes this instance of %RandomIteratorT class.
  54          *
  55          * @since               2.1
  56          *
  57          * @param[in]   list            A reference to the IList instance to convert
  58          * @param[in]   index   A start index
  59          * @remarks                     %RandomIteratorT only supports random accessible collection for performance.
  60          * @see                         Tizen::Base::Collection::IList::IsRandomAccessible()
  61          */
  62         explicit RandomIteratorT(const IList& list, int index = 0)
  63                 : __pList(&list)
  64                 , __index(index)
  65                 , __currentObj(static_cast< T >(const_cast< Object* >(__pList->GetAt(__index))))
  66         {
  67                 AppAssertf(list.IsRandomAccessible(), "The list is not randomly accessible. RandomIteratorT only supports random accessible collection.");
  68         }
  69
  70         /**
  71          * This is the copy constructor of the %RandomIteratorT class.
  72          *
  73          * @since               2.1
  74          *
  75          * @param[in]   rhs     A reference to the %RandomIteratorT instance
  76          */
  77         RandomIteratorT(const RandomIteratorT< T >& rhs)
  78                 : __pList(rhs.__pList)
  79                 , __index(rhs.__index)
  80                 , __currentObj(rhs.__currentObj)
  81         {
  82         }
  83
  84         /**
  85          * This is the assignment operator of the %RandomIteratorT class.
  86          *
  87          * @since               2.1
  88          *
  89          * @return              A reference to the %RandomIteratorT instance
  90          * @param[in]   rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
  91          */
  92         RandomIteratorT< T >& operator=(const RandomIteratorT< T >& rhs)
  93         {
  94                 RandomIteratorT< T > tmp(rhs);
  95                 tmp.swap(*this);
  96                 return *this;
  97         }
  98
  99         /**
 100          * This is the indirection operator for the %RandomIteratorT class.
 101          *
 102          * @since               2.1
 103          *
 104          * @return              A T type reference
 105          */
 106         T& operator*(void) const
 107         {
 108                 AppAssertf(__index >= 0 && __index < __pList->GetCount(), "It is out of range.");
 109                 return const_cast< T& >(__currentObj);
 110         }
 111
 112         /**
 113          * This is the structure dereference operator for the %RandomIteratorT class.
 114          *
 115          * @since               2.1
 116          *
 117          * @return              A T type pointer equivalent to the pointer address
 118          */
 119         T* operator->(void) const
 120         {
 121                 return &(operator*());
 122         }
 123
 124         /**
 125          * Increases __index by 1.
 126          *
 127          * @since               2.1
 128          *
 129          * @return              A reference to the %RandomIteratorT instance
 130          * @exception   E_SUCCESS                       The method is successful.
 131          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 132          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 133          * @remarks             The specific error code can be accessed using GetLastResult() method.
 134          */
 135         RandomIteratorT< T >& operator++(void)
 136         {
 137                 ++__index;
 138
 139                 // GetAt() will return null if __index is out of range.
 140                 __currentObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(__index)));
 141                 TryReturnResult(__currentObj != null, *this, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 142                 return *this;
 143         }
 144
 145         /**
 146          * Increases __index by 1 and returns the previous state.
 147          *
 148          * @since               2.1
 149          *
 150          * @return              A %RandomIteratorT instance
 151          * @exception   E_SUCCESS                       The method is successful.
 152          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 153          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 154          * @remarks             The specific error code can be accessed using GetLastResult() method.
 155          */
 156         RandomIteratorT< T > operator++(int)
 157         {
 158                 RandomIteratorT< T > tempIter = *this;
 159                 operator++();
 160                 return tempIter;
 161         }
 162
 163         /**
 164          * Decrease __index by 1.
 165          *
 166          * @since               2.1
 167          *
 168          * @return              A reference to the %RandomIteratorT instance
 169          * @exception   E_SUCCESS                       The method is successful.
 170          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 171          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 172          * @remarks             The specific error code can be accessed using GetLastResult() method.
 173          */
 174         RandomIteratorT< T >& operator--(void)
 175         {
 176                 --__index;
 177
 178                 // GetAt() will return null if __index is out of range.
 179                 __currentObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(__index)));
 180                 TryReturnResult(__currentObj != null, *this, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 181                 return *this;
 182         }
 183
 184         /**
 185          * Decrease __index by 1 and returns the previous state.
 186          *
 187          * @since               2.1
 188          *
 189          * @return              A %RandomIteratorT instance
 190          * @exception   E_SUCCESS                       The method is successful.
 191          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 192          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 193          * @remarks             The specific error code can be accessed using GetLastResult() method.
 194          */
 195         RandomIteratorT< T > operator--(int)
 196         {
 197                 RandomIteratorT< T > tempIter = *this;
 198                 operator--();
 199                 return tempIter;
 200         }
 201
 202         /**
 203          *      Checks two %RandomIteratorT instances for equality.
 204          *
 205          *      @since          2.1
 206          *
 207          *      @return         @c true if every member of the specified %RandomIteratorT instance equals the calling instance's members, @n
 208          *                              else @c false
 209          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 210          */
 211         bool operator==(const RandomIteratorT< T >& rhs) const
 212         {
 213                 return ((__pList == rhs.__pList) && (__index == rhs.__index) && (__currentObj == rhs.__currentObj));
 214         }
 215
 216         /**
 217          *      Checks two %RandomIteratorT instances for inequality.
 218          *
 219          *      @since          2.1
 220          *
 221          *      @return         @c true if any member of the specified %RandomIteratorT instance is not equal to the calling instance's members, @n
 222          *                              else @c false
 223          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 224          */
 225         bool operator!=(const RandomIteratorT< T >& rhs) const
 226         {
 227                 return !operator==(rhs);
 228         }
 229
 230         /**
 231          *      Checks l-value is less than r-value.
 232          *
 233          *      @since          2.1
 234          *
 235          *      @return         @c true if l-value of the specified %RandomIteratorT instance is less than the calling instance's members, @n
 236          *                              else @c false
 237          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 238          */
 239         bool operator<(const RandomIteratorT< T >& rhs) const
 240         {
 241                 return __index < rhs.__index;
 242         }
 243
 244         /**
 245          *      Checks whether l-value is greater than r-value.
 246          *
 247          *      @since          2.1
 248          *
 249          *      @return         @c true if l-value of the specified %RandomIteratorT instance is greater than the calling instance's members, @n
 250          *                              else @c false
 251          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 252          */
 253         bool operator>(const RandomIteratorT< T >& rhs) const
 254         {
 255                 return __index > rhs.__index;
 256         }
 257
 258         /**
 259          * Increases __index as specified by the diff parameter.
 260          *
 261          * @since               2.1
 262          *
 263          * @return              A %RandomIteratorT instance
 264          * @param[in]   diff            The length to move forward
 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,
 267          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 268          * @remarks             The specific error code can be accessed using GetLastResult() method.
 269          */
 270         RandomIteratorT< T > operator+(int diff)
 271         {
 272                 RandomIteratorT< T > tempIter = *this;
 273                 tempIter.__index += diff;
 274
 275                 // GetAt() will return null if __index is out of range.
 276                 tempIter.__currentObj = static_cast< T >(const_cast< Object* >(tempIter.__pList->GetAt(tempIter.__index)));
 277                 TryReturnResult(tempIter.__currentObj != null, tempIter, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 278                 return tempIter;
 279         }
 280
 281         /**
 282          * Decrease __index as specified by the diff parameter.
 283          *
 284          * @since               2.1
 285          *
 286          * @return              A %RandomIteratorT instance
 287          * @param[in]   diff            The length to move backward
 288          * @exception   E_SUCCESS                       The method is successful.
 289          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 290          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 291          * @remarks             The specific error code can be accessed using GetLastResult() method.
 292          */
 293         RandomIteratorT< T > operator-(int diff)
 294         {
 295                 RandomIteratorT< T > tempIter = *this;
 296                 tempIter.__index -= diff;
 297
 298                 // GetAt() will return null if __index is out of range.
 299                 tempIter.__currentObj = static_cast< T >(const_cast< Object* >(tempIter.__pList->GetAt(tempIter.__index)));
 300                 TryReturnResult(tempIter.__currentObj != null, tempIter, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 301                 return tempIter;
 302         }
 303
 304         int operator-(const RandomIteratorT< T >& rhs)
 305         {
 306                 return __index - rhs.__index;
 307         }
 308
 309         /**
 310          * This is the index operator for the %RandomIteratorT class.
 311          *
 312          * @since               2.1
 313          *
 314          * @return              A reference to the T type instance
 315          * @param[in]   index   An index to reach
 316          * @exception   E_SUCCESS                       The method is successful.
 317          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure,
 318          *                                                                      or the specified index is either equal to or greater than the number of elements in the list or less than 0.
 319          * @remarks             The specific error code can be accessed using GetLastResult() method.
 320          */
 321         T& operator[](int index) const
 322         {
 323                 // GetAt() will return null if __index is out of range.
 324                 const T& tempObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(index)));
 325                 TryReturnResult(tempObj != null, const_cast< T& >(tempObj), GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 326                 return const_cast< T& >(tempObj);
 327         }
 328
 329         /**
 330          *      Swaps values of the two %RandomIteratorT instances.
 331          *
 332          *      @since          2.1
 333          *
 334          *      @param[in]      rhs     A reference to the %RandomIteratorT instance to swap
 335          */
 336         void swap(RandomIteratorT< T >& rhs)
 337         {
 338                 std::swap(__pList, rhs.__pList);
 339                 std::swap(__index, rhs.__index);
 340                 std::swap(__currentObj, rhs.__currentObj);
 341         }
 342
 343 private:
 344         const IList* __pList;
 345         int __index;
 346         T __currentObj;
 347 }; // RandomIteratorT
 348
 349 }}} // Tizen::Base::Collection
 350
 351 #endif //_FBASE_COL_RANDOM_ITERATOR_T_H_