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());
93 * Gets the STL compatible iterator referring to the first element in the IList instance.
95 * @brief <i> [Deprecated] </i>
96 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
99 * @return An IteratorT instance
100 * @param[in] pList A pointer to the IList instance to convert
102 template< typename T >
103 static IteratorT< T > GetBeginIterator(const IList* pList)
105 return GetBeginIterator< T >(const_cast< IList* >(pList));
109 * Gets the STL compatible iterator referring to the first element in the IList instance.
113 * @return An IteratorT instance
114 * @param[in] pList A pointer to the IList instance to convert
115 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
117 template< typename T >
118 static IteratorT< T > GetBeginIterator(IList* pList)
120 return IteratorT< T >(*pList);
124 * Gets the STL compatible iterator referring to the post-end element in the IList instance.
126 * @brief <i> [Deprecated] </i>
127 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
130 * @return An IteratorT instance
131 * @param[in] pList A pointer to the IList instance to convert
133 template< typename T >
134 static IteratorT< T > GetEndIterator(const IList* pList)
136 return GetEndIterator< T >(const_cast< IList* >(pList));
140 * Gets the STL compatible iterator referring to the post-end element in the IList instance.
144 * @return An IteratorT instance
145 * @param[in] pList A pointer to the IList instance to convert
146 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
148 template< typename T >
149 static IteratorT< T > GetEndIterator(IList* pList)
151 return IteratorT< T >(*pList, true);
155 * Gets the STL compatible random iterator referring to the first element in the IList instance.
157 * @brief <i> [Deprecated] </i>
158 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
161 * @return A RandomIteratorT instance
162 * @param[in] pList A pointer to the IList instance to convert
164 template< typename T >
165 static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
167 return GetBeginRandomIterator< T >(const_cast< IList* >(pList));
171 * Gets the STL compatible random iterator referring to the first element in the IList instance.
175 * @return A RandomIteratorT instance
176 * @param[in] pList A pointer to the IList instance to convert
177 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
179 template< typename T >
180 static RandomIteratorT< T > GetBeginRandomIterator(IList* pList)
182 return RandomIteratorT< T >(*pList, 0);
186 * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
188 * @brief <i> [Deprecated] </i>
189 * @deprecated This method is deprecated to support mutation algorithm requiring non-const pointer.
192 * @return A RandomIteratorT instance
193 * @param[in] pList A pointer to the IList instance to convert
195 template< typename T >
196 static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
198 return GetEndRandomIterator< T >(const_cast< IList* >(pList));
202 * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
206 * @return A RandomIteratorT instance
207 * @param[in] pList A pointer to the IList instance to convert
208 * @remarks This method does not take the ownership of the @c pList because the argument is a non-const pointer.
210 template< typename T >
211 static RandomIteratorT< T > GetEndRandomIterator(IList* pList)
213 return RandomIteratorT< T >(*pList, pList->GetCount());
217 * Gets the STL compatible iterator referring to the first element in the IMap instance. @n
218 * This iterator can be used in algorithms that require paired iterators.
222 * @return A PairIteratorT instance
223 * @param[in] pMap A pointer to the IMap instance to convert
225 template< typename K, typename V >
226 static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
228 return PairIteratorT< K, V >(*pMap);
232 * Gets the STL compatible iterator referring to the post-end element in the IMap instance. @n
233 * This iterator can be used in algorithms that require paired iterators.
237 * @return A PairIteratorT instance
238 * @param[in] pMap A pointer to the IMap instance to convert
240 template< typename K, typename V >
241 static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
243 return PairIteratorT< K, V >(*pMap, true);
247 * Gets the STL compatible iterator referring to the first element in the IMultiMap instance. @n
248 * This iterator can be used in algorithms that require paired iterators.
252 * @return A PairIteratorT instance
253 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
255 template< typename K, typename V >
256 static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
258 return PairIteratorT< K, V >(*pMultiMap);
262 * Gets the STL compatible iterator referring to the post-end element in the IMultiMap instance. @n
263 * This iterator can be used in algorithms that require paired iterators.
267 * @return A PairIteratorT instance
268 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
270 template< typename K, typename V >
271 static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
273 return PairIteratorT< K, V >(*pMultiMap, true);
277 * Gets an ArrayList instance from the begin and end iterators of STL container.
281 * @return A std::unique_ptr to the ArrayList instance, @n
282 * else @c std::unique_ptr< ArrayList >() if error occurs
283 * @param[in] begin begin() of STL container
284 * @param[in] end end() of STL container
285 * @param[in] deleter The function pointer to type of the element deleter
286 * @exception E_SUCCESS The method is successful.
287 * @exception E_INVALID_ARG A specified input parameter is invalid.
288 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
289 * This gives the collection the ownership of elements and the collection can destroy elements. @n
290 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
291 * as @c NoOpDeleter is the default element deleter.
292 * That implies transfer of the ownership of elements to the collection is not required.
293 * @remarks The specific error code can be accessed using GetLastResult() method.
295 * @see SingleObjectDeleter()
296 * @see ArrayDeleter()
298 template< typename FwdIter >
299 static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
301 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
302 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
304 result r = pArrayList->Construct();
305 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
307 for (FwdIter iter = begin; iter != end; ++iter)
309 r = pArrayList->Add(*iter);
312 pArrayList->RemoveAll(false);
313 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
317 return std::move(pArrayList);
321 * Gets a LinkedList instance from the begin and end iterators of STL container.
325 * @return A std::unique_ptr to the LinkedList instance @n
326 * else @c std::unique_ptr< LinkedList >() if error occurs
327 * @param[in] begin begin() of STL container
328 * @param[in] end end() of STL container
329 * @param[in] deleter The function pointer to type of the element deleter
330 * @exception E_SUCCESS The method is successful.
331 * @exception E_INVALID_ARG A specified input parameter is invalid.
332 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
333 * This gives the collection the ownership of elements and the collection will destroy elements. @n
334 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
335 * as @c NoOpDeleter is the default element deleter.
336 * That implies transfer of the ownership of elements to the collection is not required.
337 * @remarks The specific error code can be accessed using GetLastResult() method.
339 * @see SingleObjectDeleter()
340 * @see ArrayDeleter()
342 template< typename FwdIter >
343 static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
345 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
346 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
348 for (FwdIter iter = begin; iter != end; ++iter)
350 result r = pLinkedList->Add(*iter);
353 pLinkedList->RemoveAll(false);
354 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
358 return std::move(pLinkedList);
362 * Gets a HashMap instance from the begin and end iterators of STL container.
366 * @return A std::unique_ptr to the HashMap instance @n
367 * else @c std::unique_ptr< HashMap >() if error occurs
368 * @param[in] begin begin() of STL container
369 * @param[in] end end() of STL container
370 * @param[in] deleter The function pointer to type of the element deleter
371 * @exception E_SUCCESS The method is successful.
372 * @exception E_INVALID_ARG A specified input parameter is invalid.
373 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
374 * This gives the collection the ownership of elements and the collection will destroy elements. @n
375 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
376 * as @c NoOpDeleter is the default element deleter.
377 * That implies transfer of the ownership of elements to the collection is not required.
378 * @remarks The specific error code can be accessed using GetLastResult() method.
380 * @see SingleObjectDeleter()
381 * @see ArrayDeleter()
383 template< typename PairedFwdIter >
384 static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
386 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
387 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
389 result r = pMap->Construct();
390 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
392 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
394 r = pMap->Add(pairIter->first, pairIter->second);
397 pMap->RemoveAll(false);
398 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
402 return std::move(pMap);
406 * Gets a MultiHashMap instance from the begin and end iterators of STL container.
410 * @return A std::unique_ptr to the MultiHashMap instance @n
411 * else @c std::unique_ptr< MultiHashMap >() if error occurs
412 * @param[in] begin begin() of STL container
413 * @param[in] end end() of STL container
414 * @param[in] deleter The function pointer to type of the element deleter
415 * @exception E_SUCCESS The method is successful.
416 * @exception E_INVALID_ARG A specified input parameter is invalid.
417 * @remarks To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
418 * This gives the collection the ownership of elements and the collection will destroy elements. @n
419 * On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
420 * as @c NoOpDeleter is the default element deleter.
421 * That implies transfer of the ownership of elements to the collection is not required.
422 * @remarks The specific error code can be accessed using GetLastResult() method.
424 * @see SingleObjectDeleter()
425 * @see ArrayDeleter()
427 template< typename PairedFwdIter >
428 static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
430 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
431 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
433 result r = pMultiMap->Construct();
434 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
436 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
438 r = pMultiMap->Add(pairIter->first, pairIter->second);
441 pMultiMap->RemoveAll(false);
442 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
446 return std::move(pMultiMap);
451 // This default constructor is intentionally declared as private because this class is not constructible.
458 // This destructor is intentionally declared as private because this class is not constructible.
462 virtual ~StlConverter(void);
465 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
469 // @param[in] rhs A reference to the %StlConverter instance
471 StlConverter(const StlConverter& rhs);
474 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
478 // @return A reference to the %StlConverter instance
479 // @param[in] rhs A reference to the %StlConverter instance
481 StlConverter& operator =(const StlConverter& rhs);
484 }}} // Tizen::Base::Collection
486 #endif //_FBASE_COL_STL_CONVERTER_H_