Merge "Fix Dataset for exception case" into tizen_2.1
[platform/framework/native/appfw.git] / inc / FBaseColStlConverter.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19  * @file                FBaseColStlConverter.h
20  * @brief               This is the header file for the %StlConverter class.
21  *
22  * This header file contains the declarations of the %StlConverter class.
23  */
24
25 #ifndef _FBASE_COL_STL_CONVERTER_H_
26 #define _FBASE_COL_STL_CONVERTER_H_
27
28 #include <utility>
29 #include <unique_ptr.h>
30 #include <FBaseColArrayList.h>
31 #include <FBaseColLinkedList.h>
32 #include <FBaseColHashMap.h>
33 #include <FBaseColMultiHashMap.h>
34 #include <FBaseColIteratorT.h>
35 #include <FBaseColPairIteratorT.h>
36 #include <FBaseColRandomIteratorT.h>
37 #include <FBaseColTypes.h>
38
39 namespace Tizen { namespace Base { namespace Collection
40 {
41 class IList;
42 class IMap;
43 class IMultiMap;
44
45 /**
46  *      @class  StlConverter
47  *      @brief  This class provides static methods to convert %Tizen Collection to STL Container and vice versa.
48  *
49  *      @since  2.1
50  *
51  *      The %StlConverter class provides static methods to convert %Tizen Collection to STL Container and vice versa.
52  *      The following example demonstrates how to use the %StlConverter class.
53  *
54  *      @code
55  *      #include <vector>
56  *      #include <FBase.h>
57  *      #include <FBaseCol.h>
58  *
59  *      using namespace std;
60  *      using namespace Tizen::Base;
61  *      using namespace Tizen::Base::Collection;
62  *
63  *      void
64  *      MyClass::StlConverterSample
65  *      {
66  *              // The case of Collection to STL Container
67  *              IList* pList1 = someNativeObject.GetSomeIntegerListN();
68  *
69  *              // vector can be created through IteratorT
70  *              vector< Integer* > vec1(
71  *                      StlConverter::GetBeginIterator< Integer* >(pList1),
72  *                      StlConverter::GetEndIterator< Integer* >(pList1));
73  *
74  *              // vec1 can be used here.
75  *
76  *              // The case of STL Container to Collection
77  *              vector< Integer* > vec2;
78  *
79  *              vec2.push_back(new Integer(1));
80  *              vec2.push_back(new Integer(2));
81  *              vec2.push_back(new Integer(3));
82  *
83  *              unique_ptr< ArrayList > pList2(StlConverter::GetArrayListN(vec2.begin(), vec2.end(), SingleObjectDeleter));
84  *
85  *              // call SomeNativeAPI(pList2.get());
86  *      }
87  *      @endcode
88  */
89
90 class StlConverter
91 {
92 public:
93         /**
94          * Gets the STL compatible iterator referring to the first element in the IList instance.
95          *
96          * @since               2.1
97          *
98          * @return              An IteratorT instance
99          * @param[in]   pList                   A pointer to the IList instance to convert
100          */
101         template < typename T >
102         static IteratorT< T > GetBeginIterator(const IList* pList)
103         {
104                 return IteratorT< T >(*pList);
105         }
106
107         /**
108          * Gets the STL compatible iterator referring to the post-end element in the IList instance.
109          *
110          * @since               2.1
111          *
112          * @return              An IteratorT instance
113          * @param[in]   pList                   A pointer to the IList instance to convert
114          */
115         template < typename T >
116         static IteratorT< T > GetEndIterator(const IList* pList)
117         {
118                 return IteratorT< T >(*pList, true);
119         }
120
121         /**
122          * Gets the STL compatible random iterator referring to the first element in the IList instance.
123          *
124          * @since               2.1
125          *
126          * @return              A RandomIteratorT instance
127          * @param[in]   pList                   A pointer to the IList instance to convert
128          */
129         template < typename T >
130         static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
131         {
132                 return RandomIteratorT< T >(*pList, 0);
133         }
134
135         /**
136          * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
137          *
138          * @since               2.1
139          *
140          * @return              A RandomIteratorT instance
141          * @param[in]   pList                   A pointer to the IList instance to convert
142          */
143         template < typename T >
144         static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
145         {
146                 return RandomIteratorT< T >(*pList, pList->GetCount());
147         }
148
149         /**
150          * Gets the STL compatible iterator referring to the first element in the IMap instance. @n
151          * This iterator can be used in algorithms that require paired iterators.
152          *
153          * @since               2.1
154          *
155          * @return              A PairIteratorT instance
156          * @param[in]   pMap            A pointer to the IMap instance to convert
157          */
158         template < typename K, typename V >
159         static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
160         {
161                 return PairIteratorT< K, V >(*pMap);
162         }
163
164         /**
165          * Gets the STL compatible iterator referring to the post-end element in the IMap instance. @n
166          * This iterator can be used in algorithms that require paired iterators.
167          *
168          * @since               2.1
169          *
170          * @return              A PairIteratorT instance
171          * @param[in]   pMap            A pointer to the IMap instance to convert
172          */
173         template < typename K, typename V >
174         static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
175         {
176                 return PairIteratorT< K, V >(*pMap, true);
177         }
178
179         /**
180          * Gets the STL compatible iterator referring to the first element in the IMultiMap instance. @n
181          * This iterator can be used in algorithms that require paired iterators.
182          *
183          * @since               2.1
184          *
185          * @return              A PairIteratorT instance
186          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
187          */
188         template < typename K, typename V >
189         static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
190         {
191                 return PairIteratorT< K, V >(*pMultiMap);
192         }
193
194         /**
195          * Gets the STL compatible iterator referring to the post-end element in the IMultiMap instance. @n
196          * This iterator can be used in algorithms that require paired iterators.
197          *
198          * @since               2.1
199          *
200          * @return              A PairIteratorT instance
201          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
202          */
203         template < typename K, typename V >
204         static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
205         {
206                 return PairIteratorT< K, V >(*pMultiMap, true);
207         }
208
209         /**
210          * Gets an ArrayList instance from the begin and end iterators of STL container.
211          *
212          * @since               2.1
213          *
214          * @return              A std::unique_ptr to the ArrayList instance, @n
215          *                              else @c std::unique_ptr< ArrayList >() if error occurs
216          * @param[in]   begin           begin() of STL container
217          * @param[in]   end                     end() of STL container
218          * @param[in]   deleter         The function pointer to type of the element deleter
219          * @exception   E_SUCCESS               The method is successful.
220          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
221          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
222          *                              This gives the collection the ownership of elements and the collection can destroy elements. @n
223          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
224          *                              as @c NoOpDeleter is the default element deleter.
225          *                              That implies transfer of the ownership of elements to the collection is not required.
226          * @remarks             The specific error code can be accessed using GetLastResult() method.
227          * @see                 NoOpDeleter()
228          * @see                 SingleObjectDeleter()
229          * @see                 ArrayDeleter()
230          */
231         template < typename FwdIter >
232         static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
233         {
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));
236
237                 result r = pArrayList->Construct();
238                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
239
240                 for (FwdIter iter = begin; iter != end; ++iter)
241                 {
242                         r = pArrayList->Add(*iter);
243                         if (IsFailed(r))
244                         {
245                                 pArrayList->RemoveAll(false);
246                                 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
247                         }
248                 }
249
250                 return std::move(pArrayList);
251         }
252
253         /**
254          * Gets a LinkedList instance from the begin and end iterators of STL container.
255          *
256          * @since               2.1
257          *
258          * @return              A std::unique_ptr to the LinkedList instance @n
259          *                              else @c std::unique_ptr< LinkedList >() if error occurs
260          * @param[in]   begin           begin() of STL container
261          * @param[in]   end                     end() of STL container
262          * @param[in]   deleter         The function pointer to type of the element deleter
263          * @exception   E_SUCCESS               The method is successful.
264          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
265          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
266          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
267          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
268          *                              as @c NoOpDeleter is the default element deleter.
269          *                              That implies transfer of the ownership of elements to the collection is not required.
270          * @remarks             The specific error code can be accessed using GetLastResult() method.
271          * @see                 NoOpDeleter()
272          * @see                 SingleObjectDeleter()
273          * @see                 ArrayDeleter()
274          */
275         template < typename FwdIter >
276         static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
277         {
278                 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
279                 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
280
281                 for (FwdIter iter = begin; iter != end; ++iter)
282                 {
283                         result r = pLinkedList->Add(*iter);
284                         if (IsFailed(r))
285                         {
286                                 pLinkedList->RemoveAll(false);
287                                 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
288                         }
289                 }
290
291                 return std::move(pLinkedList);
292         }
293
294         /**
295          * Gets a HashMap instance from the begin and end iterators of STL container.
296          *
297          * @since               2.1
298          *
299          * @return              A std::unique_ptr to the HashMap instance @n
300          *                              else @c std::unique_ptr< HashMap >() if error occurs
301          * @param[in]   begin           begin() of STL container
302          * @param[in]   end                     end() of STL container
303          * @param[in]   deleter         The function pointer to type of the element deleter
304          * @exception   E_SUCCESS               The method is successful.
305          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
306          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
307          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
308          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
309          *                              as @c NoOpDeleter is the default element deleter.
310          *                              That implies transfer of the ownership of elements to the collection is not required.
311          * @remarks             The specific error code can be accessed using GetLastResult() method.
312          * @see                 NoOpDeleter()
313          * @see                 SingleObjectDeleter()
314          * @see                 ArrayDeleter()
315          */
316         template < typename PairedFwdIter >
317         static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
318         {
319                 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
320                 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
321
322                 result r = pMap->Construct();
323                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
324
325                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
326                 {
327                         r = pMap->Add(pairIter->first, pairIter->second);
328                         if (IsFailed(r))
329                         {
330                                 pMap->RemoveAll(false);
331                                 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
332                         }
333                 }
334
335                 return std::move(pMap);
336         }
337
338         /**
339          * Gets a MultiHashMap instance from the begin and end iterators of STL container.
340          *
341          * @since               2.1
342          *
343          * @return              A std::unique_ptr to the MultiHashMap instance @n
344          *                              else @c std::unique_ptr< MultiHashMap >() if error occurs
345          * @param[in]   begin           begin() of STL container
346          * @param[in]   end                     end() of STL container
347          * @param[in]   deleter         The function pointer to type of the element deleter
348          * @exception   E_SUCCESS               The method is successful.
349          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
350          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
351          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
352          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
353          *                              as @c NoOpDeleter is the default element deleter.
354          *                              That implies transfer of the ownership of elements to the collection is not required.
355          * @remarks             The specific error code can be accessed using GetLastResult() method.
356          * @see                 NoOpDeleter()
357          * @see                 SingleObjectDeleter()
358          * @see                 ArrayDeleter()
359          */
360         template < typename PairedFwdIter >
361         static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
362         {
363                 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
364                 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
365
366                 result r = pMultiMap->Construct();
367                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
368
369                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
370                 {
371                         r = pMultiMap->Add(pairIter->first, pairIter->second);
372                         if (IsFailed(r))
373                         {
374                                 pMultiMap->RemoveAll(false);
375                                 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
376                         }
377                 }
378
379                 return std::move(pMultiMap);
380         }
381
382 private:
383         //
384         // This default constructor is intentionally declared as private because this class is not constructible.
385         //
386         // @since               2.1
387         //
388         StlConverter(void);
389
390         //
391         // This destructor is intentionally declared as private because this class is not constructible.
392         //
393         // @since               2.1
394         //
395         virtual ~StlConverter(void);
396
397         //
398         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
399         //
400         // @since               2.1
401         //
402         // @param[in]   rhs             A reference to the %StlConverter instance
403         //
404         StlConverter(const StlConverter& rhs);
405
406         //
407         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
408         //
409         // @since               2.1
410         //
411         // @return              A reference to the %StlConverter instance
412         // @param[in]   rhs             A reference to the %StlConverter instance
413         //
414         StlConverter& operator=(const StlConverter& rhs);
415 };
416
417 }}} // Tizen::Base::Collection
418
419 #endif //_FBASE_COL_STL_CONVERTER_H_