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 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 error occurs
 289          * @param[in]   begin           begin() of STL container
 290          * @param[in]   end                     end() of STL container
 291          * @param[in]   deleter         The function pointer to 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             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 295          *                              This gives the collection the ownership of elements and the collection can destroy elements. @n
 296          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 297          *                              as @c NoOpDeleter is the default element deleter.
 298          *                              That implies transfer of the ownership of elements to the collection is not required.
 299          * @remarks             The specific error code can be accessed using GetLastResult() method.
 300          * @see                 NoOpDeleter()
 301          * @see                 SingleObjectDeleter()
 302          * @see                 ArrayDeleter()
 303          */
 304         template< typename FwdIter >
 305         static std::unique_ptr< ArrayList > GetArrayListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 306         {
 307                 std::unique_ptr< ArrayList > pArrayList(new (std::nothrow) ArrayList(deleter));
 308                 TryReturnResult(pArrayList, std::unique_ptr< ArrayList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 309
 310                 result r = pArrayList->Construct();
 311                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 312
 313                 for (FwdIter iter = begin; iter != end; ++iter)
 314                 {
 315                         r = pArrayList->Add(*iter);
 316                         if (IsFailed(r))
 317                         {
 318                                 pArrayList->RemoveAll(false);
 319                                 TryReturnResult(false, std::unique_ptr< ArrayList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 320                         }
 321                 }
 322
 323                 return std::move(pArrayList);
 324         }
 325
 326         /**
 327          * Gets a LinkedList instance from the begin and end iterators of STL container.
 328          *
 329          * @since               2.1
 330          *
 331          * @return              A std::unique_ptr to the LinkedList instance @n
 332          *                              else @c std::unique_ptr< LinkedList >() if error occurs
 333          * @param[in]   begin           begin() of STL container
 334          * @param[in]   end                     end() of STL container
 335          * @param[in]   deleter         The function pointer to type of the element deleter
 336          * @exception   E_SUCCESS               The method is successful.
 337          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 338          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 339          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 340          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 341          *                              as @c NoOpDeleter is the default element deleter.
 342          *                              That implies transfer of the ownership of elements to the collection is not required.
 343          * @remarks             The specific error code can be accessed using GetLastResult() method.
 344          * @see                 NoOpDeleter()
 345          * @see                 SingleObjectDeleter()
 346          * @see                 ArrayDeleter()
 347          */
 348         template< typename FwdIter >
 349         static std::unique_ptr< LinkedList > GetLinkedListN(FwdIter begin, FwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 350         {
 351                 std::unique_ptr< LinkedList > pLinkedList(new (std::nothrow) LinkedList(deleter));
 352                 TryReturnResult(pLinkedList, std::unique_ptr< LinkedList >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 353
 354                 for (FwdIter iter = begin; iter != end; ++iter)
 355                 {
 356                         result r = pLinkedList->Add(*iter);
 357                         if (IsFailed(r))
 358                         {
 359                                 pLinkedList->RemoveAll(false);
 360                                 TryReturnResult(false, std::unique_ptr< LinkedList >(), r, "[%s] Propagating.", GetErrorMessage(r));
 361                         }
 362                 }
 363
 364                 return std::move(pLinkedList);
 365         }
 366
 367         /**
 368          * Gets a HashMap instance from the begin and end iterators of STL container.
 369          *
 370          * @since               2.1
 371          *
 372          * @return              A std::unique_ptr to the HashMap instance @n
 373          *                              else @c std::unique_ptr< HashMap >() if error occurs
 374          * @param[in]   begin           begin() of STL container
 375          * @param[in]   end                     end() of STL container
 376          * @param[in]   deleter         The function pointer to type of the element deleter
 377          * @exception   E_SUCCESS               The method is successful.
 378          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 379          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 380          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 381          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 382          *                              as @c NoOpDeleter is the default element deleter.
 383          *                              That implies transfer of the ownership of elements to the collection is not required.
 384          * @remarks             The specific error code can be accessed using GetLastResult() method.
 385          * @see                 NoOpDeleter()
 386          * @see                 SingleObjectDeleter()
 387          * @see                 ArrayDeleter()
 388          */
 389         template< typename PairedFwdIter >
 390         static std::unique_ptr< HashMap > GetHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 391         {
 392                 std::unique_ptr< HashMap > pMap(new (std::nothrow) HashMap(deleter));
 393                 TryReturnResult(pMap, std::unique_ptr< HashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 394
 395                 result r = pMap->Construct();
 396                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 397
 398                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 399                 {
 400                         r = pMap->Add(pairIter->first, pairIter->second);
 401                         if (IsFailed(r))
 402                         {
 403                                 pMap->RemoveAll(false);
 404                                 TryReturnResult(false, std::unique_ptr< HashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 405                         }
 406                 }
 407
 408                 return std::move(pMap);
 409         }
 410
 411         /**
 412          * Gets a MultiHashMap instance from the begin and end iterators of STL container.
 413          *
 414          * @since               2.1
 415          *
 416          * @return              A std::unique_ptr to the MultiHashMap instance @n
 417          *                              else @c std::unique_ptr< MultiHashMap >() if error occurs
 418          * @param[in]   begin           begin() of STL container
 419          * @param[in]   end                     end() of STL container
 420          * @param[in]   deleter         The function pointer to type of the element deleter
 421          * @exception   E_SUCCESS               The method is successful.
 422          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 423          * @remarks             To create an owning collection, set the element deleter value as @c SingleObjectDeleter.
 424          *                              This gives the collection the ownership of elements and the collection will destroy elements. @n
 425          *                              On the other hand, to create a non-owning collection, you don't need to set the element deleter value,
 426          *                              as @c NoOpDeleter is the default element deleter.
 427          *                              That implies transfer of the ownership of elements to the collection is not required.
 428          * @remarks             The specific error code can be accessed using GetLastResult() method.
 429          * @see                 NoOpDeleter()
 430          * @see                 SingleObjectDeleter()
 431          * @see                 ArrayDeleter()
 432          */
 433         template< typename PairedFwdIter >
 434         static std::unique_ptr< MultiHashMap > GetMultiHashMapN(PairedFwdIter begin, PairedFwdIter end, DeleterFunctionType deleter = NoOpDeleter)
 435         {
 436                 std::unique_ptr< MultiHashMap > pMultiMap(new (std::nothrow) MultiHashMap(deleter));
 437                 TryReturnResult(pMultiMap, std::unique_ptr< MultiHashMap >(), E_OUT_OF_MEMORY, "[%s] Memory allocation failed.", GetErrorMessage(E_OUT_OF_MEMORY));
 438
 439                 result r = pMultiMap->Construct();
 440                 TryReturnResult(r == E_SUCCESS, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 441
 442                 for (PairedFwdIter pairIter = begin; pairIter != end; ++pairIter)
 443                 {
 444                         r = pMultiMap->Add(pairIter->first, pairIter->second);
 445                         if (IsFailed(r))
 446                         {
 447                                 pMultiMap->RemoveAll(false);
 448                                 TryReturnResult(false, std::unique_ptr< MultiHashMap >(), r, "[%s] Propagating.", GetErrorMessage(r));
 449                         }
 450                 }
 451
 452                 return std::move(pMultiMap);
 453         }
 454
 455 private:
 456         //
 457         // This default constructor is intentionally declared as private because this class is not constructible.
 458         //
 459         // @since               2.1
 460         //
 461         StlConverter(void);
 462
 463         //
 464         // This destructor is intentionally declared as private because this class is not constructible.
 465         //
 466         // @since               2.1
 467         //
 468         virtual ~StlConverter(void);
 469
 470         //
 471         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 472         //
 473         // @since               2.1
 474         //
 475         // @param[in]   rhs             A reference to the %StlConverter instance
 476         //
 477         StlConverter(const StlConverter& rhs);
 478
 479         //
 480         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 481         //
 482         // @since               2.1
 483         //
 484         // @return              A reference to the %StlConverter instance
 485         // @param[in]   rhs             A reference to the %StlConverter instance
 486         //
 487         StlConverter& operator =(const StlConverter& rhs);
 488 };
 489
 490 }}} // Tizen::Base::Collection
 491
 492 #endif //_FBASE_COL_STL_CONVERTER_H_