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  */
  88
  89 class StlConverter
  90 {
  91 public:
  92         /**
  93          * Gets the STL compatible iterator referring to the first element in the IList instance.
  94          *
  95          * @since               2.1
  96          *
  97          * @return              An IteratorT instance
  98          * @param[in]   pList                   A pointer to the IList instance to convert
  99          */
 100         template< typename T >
 101         static IteratorT< T > GetBeginIterator(const IList* pList)
 102         {
 103                 return IteratorT< T >(*pList);
 104         }
 105
 106         /**
 107          * Gets the STL compatible iterator referring to the post-end element in the IList instance.
 108          *
 109          * @since               2.1
 110          *
 111          * @return              An IteratorT instance
 112          * @param[in]   pList                   A pointer to the IList instance to convert
 113          */
 114         template< typename T >
 115         static IteratorT< T > GetEndIterator(const IList* pList)
 116         {
 117                 return IteratorT< T >(*pList, true);
 118         }
 119
 120         /**
 121          * Gets the STL compatible random iterator referring to the first element in the IList instance.
 122          *
 123          * @since               2.1
 124          *
 125          * @return              A RandomIteratorT instance
 126          * @param[in]   pList                   A pointer to the IList instance to convert
 127          */
 128         template< typename T >
 129         static RandomIteratorT< T > GetBeginRandomIterator(const IList* pList)
 130         {
 131                 return RandomIteratorT< T >(*pList, 0);
 132         }
 133
 134         /**
 135          * Gets the STL compatible random iterator referring to the post-end element in the IList instance.
 136          *
 137          * @since               2.1
 138          *
 139          * @return              A RandomIteratorT instance
 140          * @param[in]   pList                   A pointer to the IList instance to convert
 141          */
 142         template< typename T >
 143         static RandomIteratorT< T > GetEndRandomIterator(const IList* pList)
 144         {
 145                 return RandomIteratorT< T >(*pList, pList->GetCount());
 146         }
 147
 148         /**
 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.
 151          *
 152          * @since               2.1
 153          *
 154          * @return              A PairIteratorT instance
 155          * @param[in]   pMap            A pointer to the IMap instance to convert
 156          */
 157         template< typename K, typename V >
 158         static PairIteratorT< K, V > GetBeginPairIterator(const IMap* pMap)
 159         {
 160                 return PairIteratorT< K, V >(*pMap);
 161         }
 162
 163         /**
 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.
 166          *
 167          * @since               2.1
 168          *
 169          * @return              A PairIteratorT instance
 170          * @param[in]   pMap            A pointer to the IMap instance to convert
 171          */
 172         template< typename K, typename V >
 173         static PairIteratorT< K, V > GetEndPairIterator(const IMap* pMap)
 174         {
 175                 return PairIteratorT< K, V >(*pMap, true);
 176         }
 177
 178         /**
 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.
 181          *
 182          * @since               2.1
 183          *
 184          * @return              A PairIteratorT instance
 185          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
 186          */
 187         template< typename K, typename V >
 188         static PairIteratorT< K, V > GetBeginPairIterator(const IMultiMap* pMultiMap)
 189         {
 190                 return PairIteratorT< K, V >(*pMultiMap);
 191         }
 192
 193         /**
 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.
 196          *
 197          * @since               2.1
 198          *
 199          * @return              A PairIteratorT instance
 200          * @param[in]   pMultiMap       A pointer to the IMultiMap instance to convert
 201          */
 202         template< typename K, typename V >
 203         static PairIteratorT< K, V > GetEndPairIterator(const IMultiMap* pMultiMap)
 204         {
 205                 return PairIteratorT< K, V >(*pMultiMap, true);
 206         }
 207
 208         /**
 209          * Gets an ArrayList instance from the begin and end iterators of STL container.
 210          *
 211          * @since               2.1
 212          *
 213          * @return              A std::unique_ptr to the ArrayList instance, @n
 214          *                              else @c std::unique_ptr< ArrayList >() if error occurs
 215          * @param[in]   begin           begin() of STL container
 216          * @param[in]   end                     end() of STL container
 217          * @param[in]   deleter         The function pointer to type of the element deleter
 218          * @exception   E_SUCCESS               The method is successful.
 219          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 220          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 221          *                              This gives the collection the ownership of elements and the collection can destroy elements. @n
 222          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 223          *                              as @c NoOpDeleter is the default element deleter.
 224          *                              That implies transfer of the ownership of elements to the collection is not required.
 225          * @remarks             The specific error code can be accessed using GetLastResult() method.
 226          * @see                 NoOpDeleter()
 227          * @see                 SingleObjectDeleter()
 228          * @see                 ArrayDeleter()
 229          */
 230         template< typename FwdIter >
 231         static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 232         {
 233                 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
 234                 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 235
 236                 result r = pArrayList->Construct();
 237                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 238
 239                 for (FwdIter iter = begin; iter != end; ++iter)
 240                 {
 241                         r = pArrayList->Add(*iter);
 242                         if (IsFailed(r))
 243                         {
 244                                 pArrayList->RemoveAll(false);
 245                                 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 246                         }
 247                 }
 248
 249                 return std::move(pArrayList);
 250         }
 251
 252         /**
 253          * Gets a LinkedList instance from the begin and end iterators of STL container.
 254          *
 255          * @since               2.1
 256          *
 257          * @return              A std::unique_ptr to the LinkedList instance @n
 258          *                              else @c std::unique_ptr< LinkedList >() if error occurs
 259          * @param[in]   begin           begin() of STL container
 260          * @param[in]   end                     end() of STL container
 261          * @param[in]   deleter         The function pointer to type of the element deleter
 262          * @exception   E_SUCCESS               The method is successful.
 263          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 264          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 265          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 266          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 267          *                              as @c NoOpDeleter is the default element deleter.
 268          *                              That implies transfer of the ownership of elements to the collection is not required.
 269          * @remarks             The specific error code can be accessed using GetLastResult() method.
 270          * @see                 NoOpDeleter()
 271          * @see                 SingleObjectDeleter()
 272          * @see                 ArrayDeleter()
 273          */
 274         template< typename FwdIter >
 275         static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 276         {
 277                 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
 278                 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 279
 280                 for (FwdIter iter = begin; iter != end; ++iter)
 281                 {
 282                         result r = pLinkedList->Add(*iter);
 283                         if (IsFailed(r))
 284                         {
 285                                 pLinkedList->RemoveAll(false);
 286                                 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 287                         }
 288                 }
 289
 290                 return std::move(pLinkedList);
 291         }
 292
 293         /**
 294          * Gets a HashMap instance from the begin and end iterators of STL container.
 295          *
 296          * @since               2.1
 297          *
 298          * @return              A std::unique_ptr to the HashMap instance @n
 299          *                              else @c std::unique_ptr< HashMap >() if error occurs
 300          * @param[in]   begin           begin() of STL container
 301          * @param[in]   end                     end() of STL container
 302          * @param[in]   deleter         The function pointer to type of the element deleter
 303          * @exception   E_SUCCESS               The method is successful.
 304          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 305          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 306          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 307          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 308          *                              as @c NoOpDeleter is the default element deleter.
 309          *                              That implies transfer of the ownership of elements to the collection is not required.
 310          * @remarks             The specific error code can be accessed using GetLastResult() method.
 311          * @see                 NoOpDeleter()
 312          * @see                 SingleObjectDeleter()
 313          * @see                 ArrayDeleter()
 314          */
 315         template< typename PairedFwdIter >
 316         static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 317         {
 318                 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
 319                 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 320
 321                 result r = pMap->Construct();
 322                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 323
 324                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 325                 {
 326                         r = pMap->Add(pairIter->first, pairIter->second);
 327                         if (IsFailed(r))
 328                         {
 329                                 pMap->RemoveAll(false);
 330                                 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 331                         }
 332                 }
 333
 334                 return std::move(pMap);
 335         }
 336
 337         /**
 338          * Gets a MultiHashMap instance from the begin and end iterators of STL container.
 339          *
 340          * @since               2.1
 341          *
 342          * @return              A std::unique_ptr to the MultiHashMap instance @n
 343          *                              else @c std::unique_ptr< MultiHashMap >() if error occurs
 344          * @param[in]   begin           begin() of STL container
 345          * @param[in]   end                     end() of STL container
 346          * @param[in]   deleter         The function pointer to type of the element deleter
 347          * @exception   E_SUCCESS               The method is successful.
 348          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 349          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 350          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 351          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 352          *                              as @c NoOpDeleter is the default element deleter.
 353          *                              That implies transfer of the ownership of elements to the collection is not required.
 354          * @remarks             The specific error code can be accessed using GetLastResult() method.
 355          * @see                 NoOpDeleter()
 356          * @see                 SingleObjectDeleter()
 357          * @see                 ArrayDeleter()
 358          */
 359         template< typename PairedFwdIter >
 360         static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 361         {
 362                 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
 363                 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 364
 365                 result r = pMultiMap->Construct();
 366                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 367
 368                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 369                 {
 370                         r = pMultiMap->Add(pairIter->first, pairIter->second);
 371                         if (IsFailed(r))
 372                         {
 373                                 pMultiMap->RemoveAll(false);
 374                                 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 375                         }
 376                 }
 377
 378                 return std::move(pMultiMap);
 379         }
 380
 381 private:
 382         //
 383         // This default constructor is intentionally declared as private because this class is not constructible.
 384         //
 385         // @since               2.1
 386         //
 387         StlConverter(void);
 388
 389         //
 390         // This destructor is intentionally declared as private because this class is not constructible.
 391         //
 392         // @since               2.1
 393         //
 394         virtual ~StlConverter(void);
 395
 396         //
 397         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 398         //
 399         // @since               2.1
 400         //
 401         // @param[in]   rhs             A reference to the %StlConverter instance
 402         //
 403         StlConverter(const StlConverter& rhs);
 404
 405         //
 406         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 407         //
 408         // @since               2.1
 409         //
 410         // @return              A reference to the %StlConverter instance
 411         // @param[in]   rhs             A reference to the %StlConverter instance
 412         //
 413         StlConverter& operator =(const StlConverter& rhs);
 414 };
 415
 416 }}} // Tizen::Base::Collection
 417
 418 #endif //_FBASE_COL_STL_CONVERTER_H_