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.
97 * @return An IteratorT instance
98 * @param[in] pList A pointer to the IList instance to convert
100 template< typename T >
101 static IteratorT< T > GetBeginIterator(const IList* pList)
103 return IteratorT< T >(*pList);
107 * Gets the STL compatible iterator referring to the post-end element in the IList instance.
111 * @return An IteratorT instance
112 * @param[in] pList A pointer to the IList instance to convert
114 template< typename T >
115 static IteratorT< T > GetEndIterator(const IList* pList)
117 return IteratorT< T >(*pList, true);
121 * Gets the STL compatible random iterator referring to the first element in the IList instance.
125 * @return A RandomIteratorT instance
126 * @param[in] pList A pointer to the IList instance to convert
128 template< typename T >
129 static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
131 return RandomIteratorT< T >(*pList, 0);
135 * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
139 * @return A RandomIteratorT instance
140 * @param[in] pList A pointer to the IList instance to convert
142 template< typename T >
143 static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
145 return RandomIteratorT< T >(*pList, pList->GetCount());
149 * Gets the STL compatible iterator referring to the first element in the IMap instance. @n
150 * This iterator can be used in algorithms that require paired iterators.
154 * @return A PairIteratorT instance
155 * @param[in] pMap A pointer to the IMap instance to convert
157 template< typename K, typename V >
158 static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
160 return PairIteratorT< K, V >(*pMap);
164 * Gets the STL compatible iterator referring to the post-end element in the IMap instance. @n
165 * This iterator can be used in algorithms that require paired iterators.
169 * @return A PairIteratorT instance
170 * @param[in] pMap A pointer to the IMap instance to convert
172 template< typename K, typename V >
173 static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
175 return PairIteratorT< K, V >(*pMap, true);
179 * Gets the STL compatible iterator referring to the first element in the IMultiMap instance. @n
180 * This iterator can be used in algorithms that require paired iterators.
184 * @return A PairIteratorT instance
185 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
187 template< typename K, typename V >
188 static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
190 return PairIteratorT< K, V >(*pMultiMap);
194 * Gets the STL compatible iterator referring to the post-end element in the IMultiMap instance. @n
195 * This iterator can be used in algorithms that require paired iterators.
199 * @return A PairIteratorT instance
200 * @param[in] pMultiMap A pointer to the IMultiMap instance to convert
202 template< typename K, typename V >
203 static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
205 return PairIteratorT< K, V >(*pMultiMap, true);
209 * Gets an ArrayList instance from the begin and end iterators of the STL container.
213 * @return A std::unique_ptr to the ArrayList instance, @n
214 * else @c std::unique_ptr< ArrayList >() if an error occurs
215 * @param[in] begin begin() of the STL container
216 * @param[in] end end() of the STL container
217 * @param[in] deleter A function pointer to the type of the element deleter
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_INVALID_ARG A specified input parameter is invalid.
221 * - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
222 * This gives the collection the ownership of the elements and the collection can destroy the elements. @n
223 * On the other hand, to create a non-owning collection, do not set the element deleter value,
224 * as @c NoOpDeleter is the default element deleter. @n
225 * This implies that the transfer of the ownership of the elements to the collection is not required.
226 * - The specific error code can be accessed using GetLastResult() method.
228 * @see SingleObjectDeleter()
229 * @see ArrayDeleter()
231 template< typename FwdIter >
232 static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
234 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
235 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
237 result r = pArrayList->Construct();
238 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
240 for (FwdIter iter = begin; iter != end; ++iter)
242 r = pArrayList->Add(*iter);
245 pArrayList->RemoveAll(false);
246 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
250 return std::move(pArrayList);
254 * Gets a LinkedList instance from the begin and end iterators of the STL container.
258 * @return A std::unique_ptr to the LinkedList instance @n
259 * else @c std::unique_ptr< LinkedList >() if an error occurs
260 * @param[in] begin begin() of the STL container
261 * @param[in] end end() of the STL container
262 * @param[in] deleter A function pointer to the type of the element deleter
263 * @exception E_SUCCESS The method is successful.
264 * @exception E_INVALID_ARG A specified input parameter is invalid.
266 * - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
267 * This gives the collection the ownership of the elements and the collection can destroy the elements. @n
268 * On the other hand, to create a non-owning collection, do not set the element deleter value,
269 * as @c NoOpDeleter is the default element deleter. @n
270 * This implies that the transfer of the ownership of the elements to the collection is not required.
271 * - The specific error code can be accessed using GetLastResult() method.
273 * @see SingleObjectDeleter()
274 * @see ArrayDeleter()
276 template< typename FwdIter >
277 static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
279 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
280 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
282 for (FwdIter iter = begin; iter != end; ++iter)
284 result r = pLinkedList->Add(*iter);
287 pLinkedList->RemoveAll(false);
288 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
292 return std::move(pLinkedList);
296 * Gets a HashMap instance from the begin and end iterators of the STL container.
300 * @return A std::unique_ptr to the HashMap instance @n
301 * else @c std::unique_ptr< HashMap >() if an error occurs
302 * @param[in] begin begin() of the STL container
303 * @param[in] end end() of the STL container
304 * @param[in] deleter A function pointer to the type of the element deleter
305 * @exception E_SUCCESS The method is successful.
306 * @exception E_INVALID_ARG A specified input parameter is invalid.
308 * - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
309 * This gives the collection the ownership of the elements and the collection can destroy the elements. @n
310 * On the other hand, to create a non-owning collection, do not set the element deleter value,
311 * as @c NoOpDeleter is the default element deleter. @n
312 * This implies that the transfer of the ownership of the elements to the collection is not required.
313 * - The specific error code can be accessed using GetLastResult() method.
315 * @see SingleObjectDeleter()
316 * @see ArrayDeleter()
318 template< typename PairedFwdIter >
319 static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
321 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
322 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
324 result r = pMap->Construct();
325 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
327 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
329 r = pMap->Add(pairIter->first, pairIter->second);
332 pMap->RemoveAll(false);
333 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
337 return std::move(pMap);
341 * Gets a MultiHashMap instance from the begin and end iterators of the STL container.
345 * @return A std::unique_ptr to the MultiHashMap instance @n
346 * else @c std::unique_ptr< MultiHashMap >() if an error occurs
347 * @param[in] begin begin() of the STL container
348 * @param[in] end end() of the STL container
349 * @param[in] deleter A function pointer to the type of the element deleter
350 * @exception E_SUCCESS The method is successful.
351 * @exception E_INVALID_ARG A specified input parameter is invalid.
353 * - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
354 * This gives the collection the ownership of the elements and the collection can destroy the elements. @n
355 * On the other hand, to create a non-owning collection, do not set the element deleter value,
356 * as @c NoOpDeleter is the default element deleter. @n
357 * This implies that the transfer of the ownership of the elements to the collection is not required.
358 * - The specific error code can be accessed using GetLastResult() method.
360 * @see SingleObjectDeleter()
361 * @see ArrayDeleter()
363 template< typename PairedFwdIter >
364 static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
366 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
367 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
369 result r = pMultiMap->Construct();
370 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
372 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
374 r = pMultiMap->Add(pairIter->first, pairIter->second);
377 pMultiMap->RemoveAll(false);
378 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
382 return std::move(pMultiMap);
387 // This default constructor is intentionally declared as private because this class is not constructible.
394 // This destructor is intentionally declared as private because this class is not constructible.
398 virtual ~StlConverter(void);
401 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
405 // @param[in] rhs A reference to the %StlConverter instance
407 StlConverter(const StlConverter& rhs);
410 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
414 // @return A reference to the %StlConverter instance
415 // @param[in] rhs A reference to the %StlConverter instance
417 StlConverter& operator =(const StlConverter& rhs);
420 }}} // Tizen::Base::Collection
422 #endif //_FBASE_COL_STL_CONVERTER_H_