Merge "Update deprecated libprivilege-control API functions." into tizen
[platform/framework/native/appfw.git] / inc / FBaseColStlConverter.h
1 //
2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
3 //
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
7 //
8 // http://www.apache.org/licenses/LICENSE-2.0
9 //
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.
15 //
16
17 /**
18  * @file                FBaseColStlConverter.h
19  * @brief               This is the header file for the %StlConverter class.
20  *
21  * This header file contains the declarations of the %StlConverter class.
22  */
23
24 #ifndef _FBASE_COL_STL_CONVERTER_H_
25 #define _FBASE_COL_STL_CONVERTER_H_
26
27 #include <utility>
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>
37
38 namespace Tizen { namespace Base { namespace Collection
39 {
40 class IList;
41 class IMap;
42 class IMultiMap;
43
44 /**
45  *      @class  StlConverter
46  *      @brief  This class provides static methods to convert %Tizen %Collection to STL Container and vice versa.
47  *
48  *      @since  2.1
49  *
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.
52  *
53  *      @code
54  *      #include <vector>
55  *      #include <FBase.h>
56  *      #include <FBaseCol.h>
57  *
58  *      using namespace std;
59  *      using namespace Tizen::Base;
60  *      using namespace Tizen::Base::Collection;
61  *
62  *      void
63  *      MyClass::StlConverterSample
64  *      {
65  *              // The case of Collection to STL Container
66  *              IList* pList1 = someNativeObject.GetSomeIntegerListN();
67  *
68  *              // vector can be created through IteratorT
69  *              vector< Integer* > vec1(
70  *                      StlConverter::GetBeginIterator< Integer* >(pList1),
71  *                      StlConverter::GetEndIterator< Integer* >(pList1));
72  *
73  *              // vec1 can be used here.
74  *
75  *              // The case of STL Container to Collection
76  *              vector< Integer* > vec2;
77  *
78  *              vec2.push_back(new Integer(1));
79  *              vec2.push_back(new Integer(2));
80  *              vec2.push_back(new Integer(3));
81  *
82  *              unique_ptr< ArrayList > pList2(StlConverter::GetArrayListN(vec2.begin(), vec2.end(), SingleObjectDeleter));
83  *
84  *              // call SomeNativeAPI(pList2.get());
85  *      }
86  *      @endcode
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.
93  */
94
95 class StlConverter
96 {
97 public:
98         /**
99          * Gets the STL compatible iterator referring to the first element in the IList instance.
100          *
101          * @brief       <i> [Deprecated] </i>
102          * @deprecated  This method is deprecated to support mutation algorithm requiring non-const pointer.
103          * @since               2.1
104          *
105          * @return              An IteratorT instance
106          * @param[in]   pList                   A pointer to the IList instance to convert
107          */
108         template< typename T >
109         static IteratorT< T > GetBeginIterator(const IList* pList)
110         {
111                 return GetBeginIterator< T >(const_cast< IList* >(pList));
112         }
113
114         /**
115          * Gets the STL compatible iterator referring to the first element in the IList instance.
116          *
117          * @since               3.0
118          *
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.
122          */
123         template< typename T >
124         static IteratorT< T > GetBeginIterator(IList* pList)
125         {
126                 return IteratorT< T >(*pList);
127         }
128
129         /**
130          * Gets the STL compatible iterator referring to the post-end element in the IList instance.
131          *
132          * @brief       <i> [Deprecated] </i>
133          * @deprecated  This method is deprecated to support mutation algorithm requiring non-const pointer.
134          * @since               2.1
135          *
136          * @return              An IteratorT instance
137          * @param[in]   pList                   A pointer to the IList instance to convert
138          */
139         template< typename T >
140         static IteratorT< T > GetEndIterator(const IList* pList)
141         {
142                 return GetEndIterator< T >(const_cast< IList* >(pList));
143         }
144
145         /**
146          * Gets the STL compatible iterator referring to the post-end element in the IList instance.
147          *
148          * @since               3.0
149          *
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.
153          */
154         template< typename T >
155         static IteratorT< T > GetEndIterator(IList* pList)
156         {
157                 return IteratorT< T >(*pList, true);
158         }
159
160         /**
161          * Gets the STL compatible random iterator referring to the first element in the IList instance.
162          *
163          * @brief       <i> [Deprecated] </i>
164          * @deprecated  This method is deprecated to support mutation algorithm requiring non-const pointer.
165          * @since               2.1
166          *
167          * @return              A RandomIteratorT instance
168          * @param[in]   pList                   A pointer to the IList instance to convert
169          */
170         template< typename T >
171         static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
172         {
173                 return GetBeginRandomIterator< T >(const_cast< IList* >(pList));
174         }
175
176         /**
177          * Gets the STL compatible random iterator referring to the first element in the IList instance.
178          *
179          * @since               3.0
180          *
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.
184          */
185         template< typename T >
186         static RandomIteratorT< T > GetBeginRandomIterator(IList* pList)
187         {
188                 return RandomIteratorT< T >(*pList, 0);
189         }
190
191         /**
192          * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
193          *
194          * @brief       <i> [Deprecated] </i>
195          * @deprecated  This method is deprecated to support mutation algorithm requiring non-const pointer.
196          * @since               2.1
197          *
198          * @return              A RandomIteratorT instance
199          * @param[in]   pList                   A pointer to the IList instance to convert
200          */
201         template< typename T >
202         static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
203         {
204                 return GetEndRandomIterator< T >(const_cast< IList* >(pList));
205         }
206
207         /**
208          * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
209          *
210          * @since               3.0
211          *
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.
215          */
216         template< typename T >
217         static RandomIteratorT< T > GetEndRandomIterator(IList* pList)
218         {
219                 return RandomIteratorT< T >(*pList, pList->GetCount());
220         }
221
222         /**
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.
225          *
226          * @since               2.1
227          *
228          * @return              A PairIteratorT instance
229          * @param[in]   pMap            A pointer to the IMap instance to convert
230          */
231         template< typename K, typename V >
232         static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
233         {
234                 return PairIteratorT< K, V >(*pMap);
235         }
236
237         /**
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.
240          *
241          * @since               2.1
242          *
243          * @return              A PairIteratorT instance
244          * @param[in]   pMap            A pointer to the IMap instance to convert
245          */
246         template< typename K, typename V >
247         static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
248         {
249                 return PairIteratorT< K, V >(*pMap, true);
250         }
251
252         /**
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.
255          *
256          * @since               2.1
257          *
258          * @return              A PairIteratorT instance
259          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
260          */
261         template< typename K, typename V >
262         static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
263         {
264                 return PairIteratorT< K, V >(*pMultiMap);
265         }
266
267         /**
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.
270          *
271          * @since               2.1
272          *
273          * @return              A PairIteratorT instance
274          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
275          */
276         template< typename K, typename V >
277         static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
278         {
279                 return PairIteratorT< K, V >(*pMultiMap, true);
280         }
281
282         /**
283          * Gets an ArrayList instance from the begin and end iterators of the STL container.
284          *
285          * @since               2.1
286          *
287          * @return              A std::unique_ptr to the ArrayList instance, @n
288          *                              else @c std::unique_ptr< ArrayList >() if an error occurs
289          * @param[in]   begin                   begin() of the STL container
290          * @param[in]   end                             end() of the STL container
291          * @param[in]   deleter                 A function pointer to the 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
295          *                              - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
296          *                              This gives the collection the ownership of the elements and the collection can destroy the elements. @n
297          *                              On the other hand, to create a non-owning collection, do not set the element deleter value,
298          *                              as @c NoOpDeleter is the default element deleter. @n
299          *                              This implies that the transfer of the ownership of the elements to the collection is not required.
300          *                              - The specific error code can be accessed using GetLastResult() method.
301          * @see                 NoOpDeleter()
302          * @see                 SingleObjectDeleter()
303          * @see                 ArrayDeleter()
304          */
305         template< typename FwdIter >
306         static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
307         {
308                 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
309                 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
310
311                 result r = pArrayList->Construct();
312                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
313
314                 for (FwdIter iter = begin; iter != end; ++iter)
315                 {
316                         r = pArrayList->Add(*iter);
317                         if (IsFailed(r))
318                         {
319                                 pArrayList->RemoveAll(false);
320                                 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
321                         }
322                 }
323
324                 return std::move(pArrayList);
325         }
326
327         /**
328          * Gets a LinkedList instance from the begin and end iterators of the STL container.
329          *
330          * @since               2.1
331          *
332          * @return              A std::unique_ptr to the LinkedList instance @n
333          *                              else @c std::unique_ptr< LinkedList >() if an error occurs
334          * @param[in]   begin                   begin() of the STL container
335          * @param[in]   end                             end() of the STL container
336          * @param[in]   deleter                 A function pointer to the type of the element deleter
337          * @exception   E_SUCCESS               The method is successful.
338          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
339          * @remarks
340          *                              - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
341          *                              This gives the collection the ownership of the elements and the collection can destroy the elements. @n
342          *                              On the other hand, to create a non-owning collection, do not set the element deleter value,
343          *                              as @c NoOpDeleter is the default element deleter. @n
344          *                              This implies that the transfer of the ownership of the elements to the collection is not required.
345          *                              - The specific error code can be accessed using GetLastResult() method.
346          * @see                 NoOpDeleter()
347          * @see                 SingleObjectDeleter()
348          * @see                 ArrayDeleter()
349          */
350         template< typename FwdIter >
351         static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
352         {
353                 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
354                 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
355
356                 for (FwdIter iter = begin; iter != end; ++iter)
357                 {
358                         result r = pLinkedList->Add(*iter);
359                         if (IsFailed(r))
360                         {
361                                 pLinkedList->RemoveAll(false);
362                                 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
363                         }
364                 }
365
366                 return std::move(pLinkedList);
367         }
368
369         /**
370          * Gets a HashMap instance from the begin and end iterators of the STL container.
371          *
372          * @since               2.1
373          *
374          * @return              A std::unique_ptr to the HashMap instance @n
375          *                              else @c std::unique_ptr< HashMap >() if an error occurs
376          * @param[in]   begin                   begin() of the STL container
377          * @param[in]   end                             end() of the STL container
378          * @param[in]   deleter                 A function pointer to the type of the element deleter
379          * @exception   E_SUCCESS               The method is successful.
380          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
381          * @remarks
382          *                              - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
383          *                              This gives the collection the ownership of the elements and the collection can destroy the elements. @n
384          *                              On the other hand, to create a non-owning collection, do not set the element deleter value,
385          *                              as @c NoOpDeleter is the default element deleter. @n
386          *                              This implies that the transfer of the ownership of the elements to the collection is not required.
387          *                              - The specific error code can be accessed using GetLastResult() method.
388          * @see                 NoOpDeleter()
389          * @see                 SingleObjectDeleter()
390          * @see                 ArrayDeleter()
391          */
392         template< typename PairedFwdIter >
393         static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
394         {
395                 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
396                 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
397
398                 result r = pMap->Construct();
399                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
400
401                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
402                 {
403                         r = pMap->Add(pairIter->first, pairIter->second);
404                         if (IsFailed(r))
405                         {
406                                 pMap->RemoveAll(false);
407                                 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
408                         }
409                 }
410
411                 return std::move(pMap);
412         }
413
414         /**
415          * Gets a MultiHashMap instance from the begin and end iterators of the STL container.
416          *
417          * @since               2.1
418          *
419          * @return              A std::unique_ptr to the MultiHashMap instance @n
420          *                              else @c std::unique_ptr< MultiHashMap >() if an error occurs
421          * @param[in]   begin                   begin() of the STL container
422          * @param[in]   end                             end() of the STL container
423          * @param[in]   deleter                 A function pointer to the type of the element deleter
424          * @exception   E_SUCCESS               The method is successful.
425          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
426          * @remarks
427          *                              - To create an owning collection, set the element deleter value as @c SingleObjectDeleter. @n
428          *                              This gives the collection the ownership of the elements and the collection can destroy the elements. @n
429          *                              On the other hand, to create a non-owning collection, do not set the element deleter value,
430          *                              as @c NoOpDeleter is the default element deleter. @n
431          *                              This implies that the transfer of the ownership of the elements to the collection is not required.
432          *                              - The specific error code can be accessed using GetLastResult() method.
433          * @see                 NoOpDeleter()
434          * @see                 SingleObjectDeleter()
435          * @see                 ArrayDeleter()
436          */
437         template< typename PairedFwdIter >
438         static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
439         {
440                 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
441                 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
442
443                 result r = pMultiMap->Construct();
444                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
445
446                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
447                 {
448                         r = pMultiMap->Add(pairIter->first, pairIter->second);
449                         if (IsFailed(r))
450                         {
451                                 pMultiMap->RemoveAll(false);
452                                 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
453                         }
454                 }
455
456                 return std::move(pMultiMap);
457         }
458
459 private:
460         //
461         // This default constructor is intentionally declared as private because this class is not constructible.
462         //
463         // @since               2.1
464         //
465         StlConverter(void);
466
467         //
468         // This destructor is intentionally declared as private because this class is not constructible.
469         //
470         // @since               2.1
471         //
472         virtual ~StlConverter(void);
473
474         //
475         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
476         //
477         // @since               2.1
478         //
479         // @param[in]   rhs             A reference to the %StlConverter instance
480         //
481         StlConverter(const StlConverter& rhs);
482
483         //
484         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
485         //
486         // @since               2.1
487         //
488         // @return              A reference to the %StlConverter instance
489         // @param[in]   rhs             A reference to the %StlConverter instance
490         //
491         StlConverter& operator =(const StlConverter& rhs);
492 };
493
494 }}} // Tizen::Base::Collection
495
496 #endif //_FBASE_COL_STL_CONVERTER_H_