inc/FBaseColRandomIteratorT.h

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