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 the requirements of the C++ standard library InputIterator concept due to the limitations of the %Tizen collection. @n
  43  *                      This class can be used with the C++ standard library algorithms which require only the 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   The starting index
  61          * @remarks             %RandomIteratorT only supports random accessible collection for its 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          Either of the following conditions has occurred:
 134          *                                                                      - The specified @c index is outside the bounds of the data structure.
 135          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 136          *                                                                      - The specified @c index is less than @c 0.
 137          * @remarks             The specific error code can be accessed using GetLastResult() method.
 138          */
 139         RandomIteratorT< T >& operator ++(void)
 140         {
 141                 ++__index;
 142
 143                 // GetAt() will return null if __index is out of range.
 144                 __currentObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(__index)));
 145                 TryReturnResult(__currentObj != null, *this, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 146                 return *this;
 147         }
 148
 149         /**
 150          * Increases __index by 1 and returns the previous state.
 151          *
 152          * @since               2.1
 153          *
 154          * @return              A %RandomIteratorT instance
 155          * @exception   E_SUCCESS                       The method is successful.
 156          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 157          *                                                                      - The specified @c index is outside the bounds of the data structure.
 158          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 159          *                                                                      - The specified @c index is less than @c 0.
 160          * @remarks             The specific error code can be accessed using GetLastResult() method.
 161          */
 162         RandomIteratorT< T > operator ++(int)
 163         {
 164                 RandomIteratorT< T > tempIter = *this;
 165                 operator ++();
 166                 return tempIter;
 167         }
 168
 169         /**
 170          * Decreases __index by 1.
 171          *
 172          * @since               2.1
 173          *
 174          * @return              A reference to the %RandomIteratorT instance
 175          * @exception   E_SUCCESS                       The method is successful.
 176          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 177          *                                                                      - The specified @c index is outside the bounds of the data structure.
 178          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 179          *                                                                      - The specified @c index is less than @c 0.
 180          * @remarks             The specific error code can be accessed using GetLastResult() method.
 181          */
 182         RandomIteratorT< T >& operator --(void)
 183         {
 184                 --__index;
 185
 186                 // GetAt() will return null if __index is out of range.
 187                 __currentObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(__index)));
 188                 TryReturnResult(__currentObj != null, *this, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 189                 return *this;
 190         }
 191
 192         /**
 193          * Decreases __index by 1 and returns the previous state.
 194          *
 195          * @since               2.1
 196          *
 197          * @return              A %RandomIteratorT instance
 198          * @exception   E_SUCCESS                       The method is successful.
 199          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 200          *                                                                      - The specified @c index is outside the bounds of the data structure.
 201          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 202          *                                                                      - The specified @c index is less than @c 0.
 203          * @remarks             The specific error code can be accessed using GetLastResult() method.
 204          */
 205         RandomIteratorT< T > operator --(int)
 206         {
 207                 RandomIteratorT< T > tempIter = *this;
 208                 operator --();
 209                 return tempIter;
 210         }
 211
 212         /**
 213          *      Checks two %RandomIteratorT instances for equality.
 214          *
 215          *      @since          2.1
 216          *
 217          *      @return         @c true if every member of the specified %RandomIteratorT instance equals the calling instance's members, @n
 218          *                              else @c false
 219          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 220          */
 221         bool operator ==(const RandomIteratorT< T >& rhs) const
 222         {
 223                 return ((__pList == rhs.__pList) && (__index == rhs.__index) && (__currentObj == rhs.__currentObj));
 224         }
 225
 226         /**
 227          *      Checks two %RandomIteratorT instances for inequality.
 228          *
 229          *      @since          2.1
 230          *
 231          *      @return         @c true if any member of the specified %RandomIteratorT instance is not equal to the calling instance's members, @n
 232          *                              else @c false
 233          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 234          */
 235         bool operator !=(const RandomIteratorT< T >& rhs) const
 236         {
 237                 return !operator ==(rhs);
 238         }
 239
 240         /**
 241          *  Checks whether the l-value is less than the r-value.
 242          *
 243          *      @since          2.1
 244          *
 245          *      @return         @c true if the l-value of the specified %RandomIteratorT instance is less than the calling instance's members, @n
 246          *                              else @c false
 247          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 248          */
 249         bool operator <(const RandomIteratorT< T >& rhs) const
 250         {
 251                 return __index < rhs.__index;
 252         }
 253
 254         /**
 255          *      Checks whether the l-value is greater than the r-value.
 256          *
 257          *      @since          2.1
 258          *
 259          *      @return         @c true if the l-value of the specified %RandomIteratorT instance is greater than the calling instance's members, @n
 260          *                              else @c false
 261          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 262          */
 263         bool operator >(const RandomIteratorT< T >& rhs) const
 264         {
 265                 return __index > rhs.__index;
 266         }
 267
 268         /**
 269          * Increases __index as specified by the @c diff parameter.
 270          *
 271          * @since               2.1
 272          *
 273          * @return              A %RandomIteratorT instance
 274          * @param[in]   diff                            The length to move forward
 275          * @exception   E_SUCCESS                       The method is successful.
 276          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 277          *                                                                      - The specified @c index is outside the bounds of the data structure.
 278          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 279          *                                                                      - The specified @c index is less than @c 0.
 280          * @remarks             The specific error code can be accessed using GetLastResult() method.
 281          */
 282         RandomIteratorT< T > operator +(int diff)
 283         {
 284                 RandomIteratorT< T > tempIter = *this;
 285                 tempIter.__index += diff;
 286
 287                 // GetAt() will return null if __index is out of range.
 288                 tempIter.__currentObj = static_cast< T >(const_cast< Object* >(tempIter.__pList->GetAt(tempIter.__index)));
 289                 TryReturnResult(tempIter.__currentObj != null, tempIter, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 290                 return tempIter;
 291         }
 292
 293         /**
 294          * Decreases __index as specified by the @c diff parameter.
 295          *
 296          * @since               2.1
 297          *
 298          * @return              A %RandomIteratorT instance
 299          * @param[in]   diff                            The length to move backward
 300          * @exception   E_SUCCESS                       The method is successful.
 301          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 302          *                                                                      - The specified @c index is outside the bounds of the data structure.
 303          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 304          *                                                                  - The specified @c index is less than @c 0.
 305          * @remarks             The specific error code can be accessed using GetLastResult() method.
 306          */
 307         RandomIteratorT< T > operator -(int diff)
 308         {
 309                 RandomIteratorT< T > tempIter = *this;
 310                 tempIter.__index -= diff;
 311
 312                 // GetAt() will return null if __index is out of range.
 313                 tempIter.__currentObj = static_cast< T >(const_cast< Object* >(tempIter.__pList->GetAt(tempIter.__index)));
 314                 TryReturnResult(tempIter.__currentObj != null, tempIter, GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 315                 return tempIter;
 316         }
 317
 318         int operator -(const RandomIteratorT< T >& rhs)
 319         {
 320                 return __index - rhs.__index;
 321         }
 322
 323         /**
 324          * This is the index operator for the %RandomIteratorT class.
 325          *
 326          * @since               2.1
 327          *
 328          * @return              A reference to the T type instance
 329          * @param[in]   index                           The index to reach
 330          * @exception   E_SUCCESS                       The method is successful.
 331          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 332          *                                                                      - The specified @c index is outside the bounds of the data structure.
 333          *                                                                      - The specified @c index is either greater than or equal to the number of elements in the list.
 334          *                                                                      - The specified @c index is less than @c 0.
 335          * @remarks             The specific error code can be accessed using GetLastResult() method.
 336          */
 337         T& operator [](int index) const
 338         {
 339                 // GetAt() will return null if __index is out of range.
 340                 const T& tempObj = static_cast< T >(const_cast< Object* >(__pList->GetAt(index)));
 341                 TryReturnResult(tempObj != null, const_cast< T& >(tempObj), GetLastResult(), "[%s] It is out of range.", GetErrorMessage(GetLastResult()));
 342                 return const_cast< T& >(tempObj);
 343         }
 344
 345         /**
 346          *      Swaps the values of the two %RandomIteratorT instances.
 347          *
 348          *      @since          2.1
 349          *
 350          *      @param[in]      rhs     A reference to the %RandomIteratorT instance to swap
 351          */
 352         void swap(RandomIteratorT< T >& rhs)
 353         {
 354                 std::swap(__pList, rhs.__pList);
 355                 std::swap(__index, rhs.__index);
 356                 std::swap(__currentObj, rhs.__currentObj);
 357         }
 358
 359 private:
 360         const IList* __pList;
 361         int __index;
 362         T __currentObj;
 363 }; // RandomIteratorT
 364
 365 }}} // Tizen::Base::Collection
 366
 367 #endif //_FBASE_COL_RANDOM_ITERATOR_T_H_