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_