dali/devel-api/common/owner-container.h

   1 #ifndef __DALI_OWNER_CONTAINER_H__
   2 #define __DALI_OWNER_CONTAINER_H__
   3
   4 /*
   5  * Copyright (c) 2017 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/common/dali-common.h>
  23 #include <dali/public-api/common/dali-vector.h>
  24
  25 namespace Dali
  26 {
  27
  28 /**
  29  * OwnerContainer is a vector which own heap-allocated objects.
  30  * Unlike vector this will call delete on the stored pointers during destruction.
  31  * For example, you can define a vector of heap-allocated Node objects:
  32  * @code
  33  *   typedef OwnerContainer< Node* > NodeContainer;
  34  *
  35  *   NodeContainer container;
  36  *   container.PushBack( new Node() );
  37  *   // container is now responsible for calling delete on Node
  38  *
  39  * @endcode
  40  */
  41 template< class T >
  42 class OwnerContainer : public Dali::Vector< T >
  43 {
  44 public:
  45
  46   typedef typename Dali::Vector< T >::SizeType SizeType;
  47   typedef typename Vector< T >::Iterator Iterator;
  48   typedef typename Vector< T >::ConstIterator ConstIterator;
  49
  50   /**
  51    * Create a pointer-container.
  52    */
  53   OwnerContainer()
  54   { }
  55
  56   /**
  57    * Non-virtual destructor; OwnerContainer<T> is not suitable as base class.
  58    */
  59   ~OwnerContainer()
  60   {
  61     Clear();
  62     VectorBase::Release();
  63   }
  64
  65   /**
  66    * Test whether the container is empty.
  67    * @return True if the container is empty
  68    */
  69   bool IsEmpty() const
  70   {
  71     return VectorBase::Count() == 0u;
  72   }
  73
  74   /**
  75    * Erase an object from the container (delete from heap).
  76    * @param[in] position A dereferencable iterator to an element in mContainer.
  77    * @return iterator pointing to next element
  78    */
  79   Iterator Erase( Iterator position )
  80   {
  81     Delete (*position);
  82     return Vector< T >::Erase( position );
  83   }
  84
  85   /**
  86    * Erase an object from OwnerContainer
  87    * @param object to remove
  88    */
  89   inline void EraseObject( T object )
  90   {
  91     DALI_ASSERT_DEBUG( object && "NULL object not allowed" );
  92
  93     Iterator iter = Vector< T >::Begin();
  94     const ConstIterator endIter = Vector< T >::End();
  95     for ( ; iter != endIter; ++iter )
  96     {
  97       if ( *iter == object )
  98       {
  99         Erase( iter );
 100         return;
 101       }
 102     }
 103   }
 104
 105   /**
 106    * Release the ownership of an object, without deleting it.
 107    * @param[in] position A dereferencable iterator to an element in mContainer.
 108    * @post iterators are invalidated by this method.
 109    * @return pointer to the released item
 110    */
 111   T Release( Iterator position )
 112   {
 113     T pointer = *position;
 114     Vector< T >::Erase( position );
 115     return pointer;
 116   }
 117
 118   /**
 119    * Destroy all of the elements in the container.
 120    */
 121   void Clear()
 122   {
 123     ConstIterator end = Vector< T >::End();
 124     for( Iterator iter = Vector< T >::Begin(); iter != end; ++iter )
 125     {
 126       Delete (*iter);
 127     }
 128     Vector< T >::Clear();
 129   }
 130
 131   /**
 132    * Resizes the container to hold specific amount of elements
 133    * @param size to resize to
 134    */
 135   void Resize( SizeType size )
 136   {
 137     if( size < VectorBase::Count() )
 138     {
 139       // OwnerContainer owns these heap-allocated objects
 140       ConstIterator end = Vector< T >::End();
 141       for( Iterator iter = Vector< T >::Begin() + size; iter != end; ++iter )
 142       {
 143         Delete (*iter);
 144       }
 145     }
 146     Vector< T >::Resize( size );
 147   }
 148
 149   /**
 150    * Move the ownership of objects from another OwnerContainer to this one
 151    * without deleting them. It will keep the original items here as well.
 152    * @param[in] source where to move elements from to this OwnerContainer
 153    */
 154   void MoveFrom( OwnerContainer& source )
 155   {
 156     typename Vector< T >::SizeType sourceCount = source.Count();
 157     // if source is empty, nothing to move
 158     if( sourceCount > 0u )
 159     {
 160       // Optimisation for the case that this is empty
 161       if( IsEmpty() )
 162       {
 163         VectorBase::Swap( source );
 164       }
 165       else
 166       {
 167         // make space for new items
 168         Vector< T >::Reserve( VectorBase::Count() + sourceCount );
 169         Iterator iter = source.Begin();
 170         ConstIterator end = source.End();
 171         for( ; iter != end; ++iter )
 172         {
 173           T pointer = *iter;
 174           Vector< T >::PushBack( pointer );
 175         }
 176         // cannot call Clear on OwnerContainer as that deletes the elements
 177         source.Vector< T >::Clear();
 178       }
 179     }
 180   }
 181
 182 private:
 183
 184   // Undefined copy constructor.
 185   OwnerContainer( const OwnerContainer& );
 186   // Undefined assignment operator.
 187   OwnerContainer& operator=( const OwnerContainer& );
 188
 189   /**
 190    * @brief delete the contents of the pointer
 191    * Function provided to allow classes to provide a custom destructor through template specialisation
 192    * @param pointer to the object
 193    */
 194   void Delete( T pointer )
 195   {
 196     delete pointer;
 197   }
 198
 199
 200 };
 201
 202 } // namespace Dali
 203
 204 #endif //__DALI_OWNER_CONTAINER_H__