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