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 FBaseColStlConverter.h
19 * @brief This is the header file for the %StlConverter class.
21 * This header file contains the declarations of the %StlConverter class.
24 #ifndef _FBASE_COL_STL_CONVERTER_H_
25 #define _FBASE_COL_STL_CONVERTER_H_
28 #include <unique_ptr.h>
29 #include <FBaseColArrayList.h>
30 #include <FBaseColLinkedList.h>
31 #include <FBaseColHashMap.h>
32 #include <FBaseColMultiHashMap.h>
33 #include <FBaseColIteratorT.h>
34 #include <FBaseColPairIteratorT.h>
35 #include <FBaseColRandomIteratorT.h>
36 #include <FBaseColTypes.h>
38 namespace Tizen { namespace Base { namespace Collection
46 * @brief This class provides static methods to convert %Tizen %Collection to STL Container and vice versa.
50 * The %StlConverter class provides static methods to convert %Tizen Collection to STL Container and vice versa.
51 * The following example demonstrates how to use the %StlConverter class.
56 * #include <FBaseCol.h>
58 * using namespace std;
59 * using namespace Tizen::Base;
60 * using namespace Tizen::Base::Collection;
63 * MyClass::StlConverterSample
65 * // The case of Collection to STL Container
66 * IList* pList1 = someNativeObject.GetSomeIntegerListN();
68 * // vector can be created through IteratorT
69 * vector< Integer* > vec1(
70 * StlConverter::GetBeginIterator< Integer* >(pList1),
71 * StlConverter::GetEndIterator< Integer* >(pList1));
73 * // vec1 can be used here.
75 * // The case of STL Container to Collection
76 * vector< Integer* > vec2;
78 * vec2.push_back(new Integer(1));
79 * vec2.push_back(new Integer(2));
80 * vec2.push_back(new Integer(3));
82 * unique_ptr< ArrayList > pList2(StlConverter::GetArrayListN(vec2.begin(), vec2.end(), SingleObjectDeleter));
84 * // call SomeNativeAPI(pList2.get());
87 * @remarks Before %Tizen 3.0, iterators managed by %StlConverter only met the requirements of the STL InputIterator concept
88 * due to the limitation of the uderlying %Tizen collection. But from %Tizen 3.0, these iterators support further STL iterator concept like below.
89 * Both IteratorT and RandomIteratorT support STL OutputIterator concept which can be dereferenced as an lvalue. It's the mutable iterator.
90 * - PairIteratorT supports STL constant ForwardIterator.
91 * - IteratorT supports STL mutable BidirectionalIterator.
92 * - RandomIteratorT supports STL mutable RandomAccessIterator.
99 * Gets the STL compatible iterator referring to the first element in the IList instance.
101 * @brief <i> [Deprecated] </i>
102 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
105 * @return An IteratorT instance
106 * @param[in] pList A pointer to the IList instance to convert
108 template< typename T >
109 static IteratorT< T > GetBeginIterator(const IList* pList)
111 return GetBeginIterator< T >(const_cast< IList* >(pList));
115 * Gets the STL compatible iterator referring to the first element in the IList instance.
119 * @return An IteratorT instance
120 * @param[in] pList A pointer to the IList instance to convert
121 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
123 template< typename T >
124 static IteratorT< T > GetBeginIterator(IList* pList)
126 return IteratorT< T >(*pList);
130 * Gets the STL compatible iterator referring to the post-end element in the IList instance.
132 * @brief <i> [Deprecated] </i>
133 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
136 * @return An IteratorT instance
137 * @param[in] pList A pointer to the IList instance to convert
139 template< typename T >
140 static IteratorT< T > GetEndIterator(const IList* pList)
142 return GetEndIterator< T >(const_cast< IList* >(pList));
146 * Gets the STL compatible iterator referring to the post-end element in the IList instance.
150 * @return An IteratorT instance
151 * @param[in] pList A pointer to the IList instance to convert
152 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
154 template< typename T >
155 static IteratorT< T > GetEndIterator(IList* pList)
157 return IteratorT< T >(*pList, true);
161 * Gets the STL compatible random iterator referring to the first element in the IList instance.
163 * @brief <i> [Deprecated] </i>
164 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
167 * @return A RandomIteratorT instance
168 * @param[in] pList A pointer to the IList instance to convert
170 template< typename T >
171 static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
173 return GetBeginRandomIterator< T >(const_cast< IList* >(pList));
177 * Gets the STL compatible random iterator referring to the first element in the IList instance.
181 * @return A RandomIteratorT instance
182 * @param[in] pList A pointer to the IList instance to convert
183 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
185 template< typename T >
186 static RandomIteratorT< T > GetBeginRandomIterator(IList* pList)
188 return RandomIteratorT< T >(*pList, 0);
192 * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
194 * @brief <i> [Deprecated] </i>
195 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
198 * @return A RandomIteratorT instance
199 * @param[in] pList A pointer to the IList instance to convert
201 template< typename T >
202 static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
204 return GetEndRandomIterator< T >(const_cast< IList* >(pList));
208 * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
212 * @return A RandomIteratorT instance
213 * @param[in] pList A pointer to the IList instance to convert
214 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
216 template< typename T >
217 static RandomIteratorT< T > GetEndRandomIterator(IList* pList)
219 return RandomIteratorT< T >(*pList, pList->GetCount());
223 * Gets the STL compatible iterator referring to the first element in the IMap instance. @n
224 * This iterator can be used in algorithms that require paired iterators.
228 * @return A PairIteratorT instance
229 * @param[in] pMap A pointer to the IMap instance to convert
231 template< typename K, typename V >
232 static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
234 return PairIteratorT< K, V >(*pMap);
238 * Gets the STL compatible iterator referring to the post-end element in the IMap instance. @n
239 * This iterator can be used in algorithms that require paired iterators.
243 * @return A PairIteratorT instance
244 * @param[in] pMap A pointer to the IMap instance to convert
246 template< typename K, typename V >
247 static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
249 return PairIteratorT< K, V >(*pMap, true);
253 * Gets the STL compatible iterator referring to the first element in the IMultiMap instance. @n
254 * This iterator can be used in algorithms that require paired iterators.
258 * @return A PairIteratorT instance
259 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
261 template< typename K, typename V >
262 static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
264 return PairIteratorT< K, V >(*pMultiMap);
268 * Gets the STL compatible iterator referring to the post-end element in the IMultiMap instance. @n
269 * This iterator can be used in algorithms that require paired iterators.
273 * @return A PairIteratorT instance
274 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
276 template< typename K, typename V >
277 static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
279 return PairIteratorT< K, V >(*pMultiMap, true);
283 * Gets an ArrayList instance from the begin and end iterators of STL container.
287 * @return A std::unique_ptr to the ArrayList instance, @n
288 * else @c std::unique_ptr< ArrayList >() if error occurs
289 * @param[in] begin begin() of STL container
290 * @param[in] end end() of STL container
291 * @param[in] deleter The function pointer to type of the element deleter
292 * @exception E_SUCCESS The method is successful.
293 * @exception E_INVALID_ARG A specified input parameter is invalid.
294 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
295 * This gives the collection the ownership of elements and the collection can destroy elements. @n
296 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
297 * as @c NoOpDeleter is the default element deleter.
298 * That implies transfer of the ownership of elements to the collection is not required.
299 * @remarks The specific error code can be accessed using GetLastResult() method.
301 * @see SingleObjectDeleter()
302 * @see ArrayDeleter()
304 template< typename FwdIter >
305 static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
307 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
308 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
310 result r = pArrayList->Construct();
311 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
313 for (FwdIter iter = begin; iter != end; ++iter)
315 r = pArrayList->Add(*iter);
318 pArrayList->RemoveAll(false);
319 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
323 return std::move(pArrayList);
327 * Gets a LinkedList instance from the begin and end iterators of STL container.
331 * @return A std::unique_ptr to the LinkedList instance @n
332 * else @c std::unique_ptr< LinkedList >() if error occurs
333 * @param[in] begin begin() of STL container
334 * @param[in] end end() of STL container
335 * @param[in] deleter The function pointer to type of the element deleter
336 * @exception E_SUCCESS The method is successful.
337 * @exception E_INVALID_ARG A specified input parameter is invalid.
338 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
339 * This gives the collection the ownership of elements and the collection will destroy elements. @n
340 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
341 * as @c NoOpDeleter is the default element deleter.
342 * That implies transfer of the ownership of elements to the collection is not required.
343 * @remarks The specific error code can be accessed using GetLastResult() method.
345 * @see SingleObjectDeleter()
346 * @see ArrayDeleter()
348 template< typename FwdIter >
349 static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
351 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
352 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
354 for (FwdIter iter = begin; iter != end; ++iter)
356 result r = pLinkedList->Add(*iter);
359 pLinkedList->RemoveAll(false);
360 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
364 return std::move(pLinkedList);
368 * Gets a HashMap instance from the begin and end iterators of STL container.
372 * @return A std::unique_ptr to the HashMap instance @n
373 * else @c std::unique_ptr< HashMap >() if error occurs
374 * @param[in] begin begin() of STL container
375 * @param[in] end end() of STL container
376 * @param[in] deleter The function pointer to type of the element deleter
377 * @exception E_SUCCESS The method is successful.
378 * @exception E_INVALID_ARG A specified input parameter is invalid.
379 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
380 * This gives the collection the ownership of elements and the collection will destroy elements. @n
381 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
382 * as @c NoOpDeleter is the default element deleter.
383 * That implies transfer of the ownership of elements to the collection is not required.
384 * @remarks The specific error code can be accessed using GetLastResult() method.
386 * @see SingleObjectDeleter()
387 * @see ArrayDeleter()
389 template< typename PairedFwdIter >
390 static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
392 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
393 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
395 result r = pMap->Construct();
396 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
398 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
400 r = pMap->Add(pairIter->first, pairIter->second);
403 pMap->RemoveAll(false);
404 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
408 return std::move(pMap);
412 * Gets a MultiHashMap instance from the begin and end iterators of STL container.
416 * @return A std::unique_ptr to the MultiHashMap instance @n
417 * else @c std::unique_ptr< MultiHashMap >() if error occurs
418 * @param[in] begin begin() of STL container
419 * @param[in] end end() of STL container
420 * @param[in] deleter The function pointer to type of the element deleter
421 * @exception E_SUCCESS The method is successful.
422 * @exception E_INVALID_ARG A specified input parameter is invalid.
423 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
424 * This gives the collection the ownership of elements and the collection will destroy elements. @n
425 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
426 * as @c NoOpDeleter is the default element deleter.
427 * That implies transfer of the ownership of elements to the collection is not required.
428 * @remarks The specific error code can be accessed using GetLastResult() method.
430 * @see SingleObjectDeleter()
431 * @see ArrayDeleter()
433 template< typename PairedFwdIter >
434 static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
436 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
437 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
439 result r = pMultiMap->Construct();
440 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
442 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
444 r = pMultiMap->Add(pairIter->first, pairIter->second);
447 pMultiMap->RemoveAll(false);
448 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
452 return std::move(pMultiMap);
457 // This default constructor is intentionally declared as private because this class is not constructible.
464 // This destructor is intentionally declared as private because this class is not constructible.
468 virtual ~StlConverter(void);
471 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
475 // @param[in] rhs A reference to the %StlConverter instance
477 StlConverter(const StlConverter& rhs);
480 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
484 // @return A reference to the %StlConverter instance
485 // @param[in] rhs A reference to the %StlConverter instance
487 StlConverter& operator =(const StlConverter& rhs);
490 }}} // Tizen::Base::Collection
492 #endif //_FBASE_COL_STL_CONVERTER_H_