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 requirements of the C++ standard library mutable RandomAccessIterator.
  43  *                      It satisfies the requirements of an OutputIterator which can be dereferenced as an lvalue.
  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::random_access_iterator_tag, T >
  52 {
  53 public:
  54         typedef std::random_access_iterator_tag iterator_category;
  55         typedef typename std::iterator_traits< RandomIteratorT< T > >::value_type value_type;
  56         typedef typename std::iterator_traits< RandomIteratorT< T > >::difference_type difference_type;
  57         typedef typename std::iterator_traits< RandomIteratorT< T > >::pointer pointer;
  58         typedef typename std::iterator_traits< RandomIteratorT< T > >::reference reference;
  59
  60         /**
  61          * This is the default constructor for this class.
  62          *
  63          * @since               3.0
  64          */
  65         RandomIteratorT(void)
  66                 : __pList(null)
  67                 , __index(0)
  68         {
  69         }
  70
  71         /**
  72          * Initializes this instance of %RandomIteratorT class.
  73          *
  74          * @since               2.1
  75          *
  76          * @param[in]   list    A reference to the IList instance to convert
  77          * @param[in]   index   A start index
  78          * @remarks             %RandomIteratorT only supports random accessible collection for performance.
  79          * @see                 Tizen::Base::Collection::IList::IsRandomAccessible()
  80          */
  81         explicit RandomIteratorT(IList& list, difference_type index = 0)
  82                 : __pList(&list)
  83                 , __index(index)
  84         {
  85                 AppAssertf(list.IsRandomAccessible(), "The list is not randomly accessible. RandomIteratorT only supports random accessible collection.");
  86         }
  87
  88         /**
  89          * This is the copy constructor of the %RandomIteratorT class.
  90          *
  91          * @since               2.1
  92          *
  93          * @param[in]   rhs     A reference to the %RandomIteratorT instance
  94          */
  95         RandomIteratorT(const RandomIteratorT< T >& rhs)
  96                 : __pList(rhs.__pList)
  97                 , __index(rhs.__index)
  98         {
  99         }
 100
 101         /**
 102          * This is the assignment operator of the %RandomIteratorT class.
 103          *
 104          * @since               2.1
 105          *
 106          * @return              A reference to the %RandomIteratorT instance
 107          * @param[in]   rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 108          */
 109         RandomIteratorT< T >& operator =(const RandomIteratorT< T >& rhs)
 110         {
 111                 RandomIteratorT< T > tmp(rhs);
 112                 tmp.swap(*this);
 113                 return *this;
 114         }
 115
 116         /**
 117          * This is the indirection operator for the %RandomIteratorT class.
 118          *
 119          * @since               2.1
 120          *
 121          * @return              A T type reference
 122          */
 123         reference operator *(void) const
 124         {
 125                 AppAssertf(__index >= 0 && __index < __pList->GetCount(), "It is out of range.");
 126                 return reinterpret_cast< T& >(__pList->GetAtRef(__index));
 127         }
 128
 129         /**
 130          * This is the structure dereference operator for the %RandomIteratorT class.
 131          *
 132          * @since               2.1
 133          *
 134          * @return              A T type pointer equivalent to the pointer address
 135          */
 136         pointer operator ->(void) const
 137         {
 138                 return &(operator *());
 139         }
 140
 141         /**
 142          * Moves to the next element in the collection.
 143          *
 144          * @since               2.1
 145          *
 146          * @return              A reference to the %RandomIteratorT instance
 147          * @exception   E_SUCCESS                       The method is successful.
 148          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 149          * @remarks             The specific error code can be accessed using GetLastResult() method.
 150          */
 151         RandomIteratorT< T >& operator ++(void)
 152         {
 153                 ClearLastResult();
 154                 ++__index;
 155                 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 156                 return *this;
 157         }
 158
 159         /**
 160          * Moves to the next element in the collection and returns the previous state.
 161          *
 162          * @since               2.1
 163          *
 164          * @return              A %RandomIteratorT instance
 165          * @exception   E_SUCCESS                       The method is successful.
 166          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 167          * @remarks             The specific error code can be accessed using GetLastResult() method.
 168          */
 169         RandomIteratorT< T > operator ++(int)
 170         {
 171                 RandomIteratorT< T > tempIter = *this;
 172                 operator ++();
 173                 return tempIter;
 174         }
 175
 176         /**
 177          * Moves to the previous element of the collection.
 178          *
 179          * @since               2.1
 180          *
 181          * @return              A reference to the %RandomIteratorT instance
 182          * @exception   E_SUCCESS                       The method is successful.
 183          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 184          * @remarks             The specific error code can be accessed using GetLastResult() method.
 185          */
 186         RandomIteratorT< T >& operator --(void)
 187         {
 188                 ClearLastResult();
 189                 --__index;
 190                 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 191                 return *this;
 192         }
 193
 194         /**
 195          * Moves to the previous element of the collection and returns the previous state.
 196          *
 197          * @since               2.1
 198          *
 199          * @return              A %RandomIteratorT instance
 200          * @exception   E_SUCCESS                       The method is successful.
 201          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 202          * @remarks             The specific error code can be accessed using GetLastResult() method.
 203          */
 204         RandomIteratorT< T > operator --(int)
 205         {
 206                 RandomIteratorT< T > tempIter = *this;
 207                 operator --();
 208                 return tempIter;
 209         }
 210
 211         /**
 212          *      Checks two %RandomIteratorT instances for equality.
 213          *
 214          *      @since          2.1
 215          *
 216          *      @return         @c true if every member of the specified %RandomIteratorT instance equals the current instance's members, @n
 217          *                              else @c false
 218          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 219          */
 220         bool operator ==(const RandomIteratorT< T >& rhs) const
 221         {
 222                 return ((__pList == rhs.__pList) && (__index == rhs.__index));
 223         }
 224
 225         /**
 226          *      Checks two %RandomIteratorT instances for inequality.
 227          *
 228          *      @since          2.1
 229          *
 230          *      @return         @c true if any member of the specified %RandomIteratorT instance is not equal to the current instance's members, @n
 231          *                              else @c false
 232          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 233          */
 234         bool operator !=(const RandomIteratorT< T >& rhs) const
 235         {
 236                 return !operator ==(rhs);
 237         }
 238
 239         /**
 240          *  Checks whether l-value is less than r-value.
 241          *
 242          *      @since          2.1
 243          *
 244          *      @return         @c true if the current instance is less than the specified %RandomIteratorT instance @n
 245          *                              else @c false
 246          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 247          */
 248         bool operator <(const RandomIteratorT< T >& rhs) const
 249         {
 250                 return __index < rhs.__index;
 251         }
 252
 253         /**
 254          *      Checks whether l-value is greater than r-value.
 255          *
 256          *      @since          2.1
 257          *
 258          *      @return         @c true if if the current instance is greater than the specified %RandomIteratorT instance @n
 259          *                              else @c false
 260          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 261          */
 262         bool operator >(const RandomIteratorT< T >& rhs) const
 263         {
 264                 return __index > rhs.__index;
 265         }
 266
 267         /**
 268          *  Checks whether l-value is less than or equal to r-value.
 269          *
 270          *      @since          3.0
 271          *
 272          *      @return         @c true if the current instance is less than or equal to the specified %RandomIteratorT instance @n
 273          *                              else @c false
 274          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 275          */
 276         bool operator <=(const RandomIteratorT< T >& rhs) const
 277         {
 278                 return __index <= rhs.__index;
 279         }
 280
 281         /**
 282          *      Checks whether l-value is greater than or equal to r-value.
 283          *
 284          *      @since          3.0
 285          *
 286          *      @return         @c true if the current instance is greater than or equal to the specified %RandomIteratorT instance @n
 287          *                              else @c false
 288          *      @param[in]      rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 289          */
 290         bool operator >=(const RandomIteratorT< T >& rhs) const
 291         {
 292                 return __index >= rhs.__index;
 293         }
 294
 295         /**
 296          * Gets the %RandomIteratorT instance which moves forward as much as specified @c diff parameter.
 297          *
 298          * @since               2.1
 299          *
 300          * @return              A %RandomIteratorT instance
 301          * @param[in]   diff                            The length to move forward
 302          * @exception   E_SUCCESS                       The method is successful.
 303          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 304          * @remarks             The specific error code can be accessed using GetLastResult() method.
 305          */
 306         RandomIteratorT< T > operator +(difference_type diff)
 307         {
 308                 ClearLastResult();
 309                 RandomIteratorT< T > tempIter = *this;
 310                 tempIter.__index += diff;
 311                 TryReturnResult(tempIter.__index >= 0 && tempIter.__index < __pList->GetCount(), tempIter, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 312                 return tempIter;
 313         }
 314
 315         /**
 316          * Gets the %RandomIteratorT instance which moves backward as much as specified @c diff parameter.
 317          *
 318          * @since               2.1
 319          *
 320          * @return              A %RandomIteratorT instance
 321          * @param[in]   diff                            The length to move backward
 322          * @exception   E_SUCCESS                       The method is successful.
 323          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 324          * @remarks             The specific error code can be accessed using GetLastResult() method.
 325          */
 326         RandomIteratorT< T > operator -(difference_type diff)
 327         {
 328                 ClearLastResult();
 329                 RandomIteratorT< T > tempIter = *this;
 330                 tempIter.__index -= diff;
 331                 TryReturnResult(tempIter.__index >= 0 && tempIter.__index < __pList->GetCount(), tempIter, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 332                 return tempIter;
 333         }
 334
 335         /**
 336          * Moves forward as much as specified @c diff parameter.
 337          *
 338          * @since               3.0
 339          *
 340          * @return              A %RandomIteratorT instance
 341          * @param[in]   diff    The length to move forward
 342          * @exception   E_SUCCESS                       The method is successful.
 343          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 344          * @remarks             The specific error code can be accessed using GetLastResult() method.
 345          */
 346         RandomIteratorT< T >& operator +=(difference_type diff)
 347         {
 348                 ClearLastResult();
 349                 __index += diff;
 350                 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 351                 return *this;
 352         }
 353
 354         /**
 355          * Moves backward as much as specified @c diff parameter.
 356          *
 357          * @since               3.0
 358          *
 359          * @return              A %RandomIteratorT instance
 360          * @param[in]   diff    The length to move backward
 361          * @exception   E_SUCCESS                       The method is successful.
 362          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 363          * @remarks             The specific error code can be accessed using GetLastResult() method.
 364          */
 365         RandomIteratorT< T >& operator -=(difference_type diff)
 366         {
 367                 ClearLastResult();
 368                 __index -= diff;
 369                 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 370                 return *this;
 371         }
 372
 373         /**
 374          * Get the difference between the current instance and the specified %RandomIteratorT instance
 375          *
 376          * @since               3.0
 377          *
 378          * @return              The difference between the current instance and the specified %RandomIteratorT instance
 379          * @param[in]   rhs     A reference to the %RandomIteratorT instance on the right-hand side of the operator
 380          */
 381         difference_type operator -(const RandomIteratorT< T >& rhs)
 382         {
 383                 return __index - rhs.__index;
 384         }
 385
 386         /**
 387          * This is the index operator for the %RandomIteratorT class.
 388          *
 389          * @since               2.1
 390          *
 391          * @return              A reference to the T type instance
 392          * @param[in]           index                           An index to move from current position
 393          * @exception   E_SUCCESS                       The method is successful.
 394          * @exception   E_OUT_OF_RANGE          The position of the iterator is outside the bounds of the list.
 395          * @remarks             The specific error code can be accessed using GetLastResult() method.
 396          */
 397         reference operator [](difference_type index)
 398         {
 399                 ClearLastResult();
 400                 reference r = reinterpret_cast< T& >(__pList->GetAtRef(__index));
 401                 TryReturnResult(__index + index >= 0 && __index + index < __pList->GetCount(), r, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
 402                 return reinterpret_cast< T& >(__pList->GetAtRef(__index + index));
 403         }
 404
 405         /**
 406          *      Swaps values of the two %RandomIteratorT instances.
 407          *
 408          *      @since          2.1
 409          *
 410          *      @param[in]      rhs     A reference to the %RandomIteratorT instance to swap
 411          */
 412         void swap(RandomIteratorT< T >& rhs)
 413         {
 414                 std::swap(__pList, rhs.__pList);
 415                 std::swap(__index, rhs.__index);
 416         }
 417
 418 private:
 419         IList* __pList;
 420         difference_type __index;
 421 }; // RandomIteratorT
 422
 423 }}} // Tizen::Base::Collection
 424
 425 #endif //_FBASE_COL_RANDOM_ITERATOR_T_H_