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