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 the 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 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.
 220          * @remarks
 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.
 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 the 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 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.
 265          * @remarks
 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.
 272          * @see                 NoOpDeleter()
 273          * @see                 SingleObjectDeleter()
 274          * @see                 ArrayDeleter()
 275          */
 276         template< typename FwdIter >
 277         static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 278         {
 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));
 281
 282                 for (FwdIter iter = begin; iter != end; ++iter)
 283                 {
 284                         result r = pLinkedList->Add(*iter);
 285                         if (IsFailed(r))
 286                         {
 287                                 pLinkedList->RemoveAll(false);
 288                                 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 289                         }
 290                 }
 291
 292                 return std::move(pLinkedList);
 293         }
 294
 295         /**
 296          * Gets a HashMap instance from the begin and end iterators of the STL container.
 297          *
 298          * @since               2.1
 299          *
 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.
 307          * @remarks
 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.
 314          * @see                 NoOpDeleter()
 315          * @see                 SingleObjectDeleter()
 316          * @see                 ArrayDeleter()
 317          */
 318         template< typename PairedFwdIter >
 319         static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 320         {
 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));
 323
 324                 result r = pMap->Construct();
 325                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 326
 327                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 328                 {
 329                         r = pMap->Add(pairIter->first, pairIter->second);
 330                         if (IsFailed(r))
 331                         {
 332                                 pMap->RemoveAll(false);
 333                                 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 334                         }
 335                 }
 336
 337                 return std::move(pMap);
 338         }
 339
 340         /**
 341          * Gets a MultiHashMap instance from the begin and end iterators of the STL container.
 342          *
 343          * @since               2.1
 344          *
 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.
 352          * @remarks
 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.
 359          * @see                 NoOpDeleter()
 360          * @see                 SingleObjectDeleter()
 361          * @see                 ArrayDeleter()
 362          */
 363         template< typename PairedFwdIter >
 364         static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 365         {
 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));
 368
 369                 result r = pMultiMap->Construct();
 370                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 371
 372                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 373                 {
 374                         r = pMultiMap->Add(pairIter->first, pairIter->second);
 375                         if (IsFailed(r))
 376                         {
 377                                 pMultiMap->RemoveAll(false);
 378                                 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 379                         }
 380                 }
 381
 382                 return std::move(pMultiMap);
 383         }
 384
 385 private:
 386         //
 387         // This default constructor is intentionally declared as private because this class is not constructible.
 388         //
 389         // @since               2.1
 390         //
 391         StlConverter(void);
 392
 393         //
 394         // This destructor is intentionally declared as private because this class is not constructible.
 395         //
 396         // @since               2.1
 397         //
 398         virtual ~StlConverter(void);
 399
 400         //
 401         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 402         //
 403         // @since               2.1
 404         //
 405         // @param[in]   rhs             A reference to the %StlConverter instance
 406         //
 407         StlConverter(const StlConverter& rhs);
 408
 409         //
 410         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 411         //
 412         // @since               2.1
 413         //
 414         // @return              A reference to the %StlConverter instance
 415         // @param[in]   rhs             A reference to the %StlConverter instance
 416         //
 417         StlConverter& operator =(const StlConverter& rhs);
 418 };
 419
 420 }}} // Tizen::Base::Collection
 421
 422 #endif //_FBASE_COL_STL_CONVERTER_H_