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