2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseColRandomIteratorT.h
19 * @brief This is the header file for the %RandomIteratorT class.
21 * This header file contains the declarations of the %RandomIteratorT class.
24 #ifndef _FBASE_COL_RANDOM_ITERATOR_T_H_
25 #define _FBASE_COL_RANDOM_ITERATOR_T_H_
27 #include <algorithm> // std::swap (Before C++11)
29 #include <FBaseColIList.h>
31 #include <FBaseObject.h>
33 namespace Tizen { namespace Base { namespace Collection
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.
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.
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.
49 template< typename T >
51 : public std::iterator< std::random_access_iterator_tag, T >
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;
61 * This is the default constructor for this class.
72 * Initializes this instance of %RandomIteratorT class.
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()
81 explicit RandomIteratorT(IList& list, difference_type index = 0)
85 AppAssertf(list.IsRandomAccessible(), "The list is not randomly accessible. RandomIteratorT only supports random accessible collection.");
89 * This is the copy constructor of the %RandomIteratorT class.
93 * @param[in] rhs A reference to the %RandomIteratorT instance
95 RandomIteratorT(const RandomIteratorT< T >& rhs)
96 : __pList(rhs.__pList)
97 , __index(rhs.__index)
102 * This is the assignment operator of the %RandomIteratorT class.
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
109 RandomIteratorT< T >& operator =(const RandomIteratorT< T >& rhs)
111 RandomIteratorT< T > tmp(rhs);
117 * This is the indirection operator for the %RandomIteratorT class.
121 * @return A T type reference
123 reference operator *(void) const
125 AppAssertf(__index >= 0 && __index < __pList->GetCount(), "It is out of range.");
126 return reinterpret_cast< T& >(__pList->GetAtRef(__index));
130 * This is the structure dereference operator for the %RandomIteratorT class.
134 * @return A T type pointer equivalent to the pointer address
136 pointer operator ->(void) const
138 return &(operator *());
142 * Moves to the next element in the collection.
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.
151 RandomIteratorT< T >& operator ++(void)
155 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
160 * Moves to the next element in the collection and returns the previous state.
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.
169 RandomIteratorT< T > operator ++(int)
171 RandomIteratorT< T > tempIter = *this;
177 * Moves to the previous element of the collection.
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.
186 RandomIteratorT< T >& operator --(void)
190 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
195 * Moves to the previous element of the collection and returns the previous state.
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.
204 RandomIteratorT< T > operator --(int)
206 RandomIteratorT< T > tempIter = *this;
212 * Checks two %RandomIteratorT instances for equality.
216 * @return @c true if every member of the specified %RandomIteratorT instance equals the current instance's members, @n
218 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
220 bool operator ==(const RandomIteratorT< T >& rhs) const
222 return ((__pList == rhs.__pList) && (__index == rhs.__index));
226 * Checks two %RandomIteratorT instances for inequality.
230 * @return @c true if any member of the specified %RandomIteratorT instance is not equal to the current instance's members, @n
232 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
234 bool operator !=(const RandomIteratorT< T >& rhs) const
236 return !operator ==(rhs);
240 * Checks whether l-value is less than r-value.
244 * @return @c true if the current instance is less than the specified %RandomIteratorT instance @n
246 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
248 bool operator <(const RandomIteratorT< T >& rhs) const
250 return __index < rhs.__index;
254 * Checks whether l-value is greater than r-value.
258 * @return @c true if if the current instance is greater than the specified %RandomIteratorT instance @n
260 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
262 bool operator >(const RandomIteratorT< T >& rhs) const
264 return __index > rhs.__index;
268 * Checks whether l-value is less than or equal to r-value.
272 * @return @c true if the current instance is less than or equal to the specified %RandomIteratorT instance @n
274 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
276 bool operator <=(const RandomIteratorT< T >& rhs) const
278 return __index <= rhs.__index;
282 * Checks whether l-value is greater than or equal to r-value.
286 * @return @c true if the current instance is greater than or equal to the specified %RandomIteratorT instance @n
288 * @param[in] rhs A reference to the %RandomIteratorT instance on the right-hand side of the operator
290 bool operator >=(const RandomIteratorT< T >& rhs) const
292 return __index >= rhs.__index;
296 * Gets the %RandomIteratorT instance which moves forward as much as specified @c diff parameter.
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.
306 RandomIteratorT< T > operator +(difference_type diff)
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));
316 * Gets the %RandomIteratorT instance which moves backward as much as specified @c diff parameter.
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.
326 RandomIteratorT< T > operator -(difference_type diff)
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));
336 * Moves forward as much as specified @c diff parameter.
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.
346 RandomIteratorT< T >& operator +=(difference_type diff)
350 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
355 * Moves backward as much as specified @c diff parameter.
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.
365 RandomIteratorT< T >& operator -=(difference_type diff)
369 TryReturnResult(__index >= 0 && __index < __pList->GetCount(), *this, E_OUT_OF_RANGE, "[%s] It is out of range.", GetErrorMessage(E_OUT_OF_RANGE));
374 * Get the difference between the current instance and the specified %RandomIteratorT instance
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
381 difference_type operator -(const RandomIteratorT< T >& rhs)
383 return __index - rhs.__index;
387 * This is the index operator for the %RandomIteratorT class.
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.
397 reference operator [](difference_type index)
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));
406 * Swaps values of the two %RandomIteratorT instances.
410 * @param[in] rhs A reference to the %RandomIteratorT instance to swap
412 void swap(RandomIteratorT< T >& rhs)
414 std::swap(__pList, rhs.__pList);
415 std::swap(__index, rhs.__index);
420 difference_type __index;
421 }; // RandomIteratorT
423 }}} // Tizen::Base::Collection
425 #endif //_FBASE_COL_RANDOM_ITERATOR_T_H_