[dali_1.2.28] Merge branch 'devel/master'
[platform/core/uifw/dali-core.git] / dali / public-api / common / dali-vector.h
1 #ifndef __DALI_VECTOR_H__
2 #define __DALI_VECTOR_H__
3
4 /*
5  * Copyright (c) 2015 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 // EXTERNAL INCLUDES
22 #include <cstddef>
23 #include <algorithm>
24
25 // INTERNAL INCLUDES
26 #include <dali/public-api/common/dali-common.h>
27 #include <dali/public-api/common/type-traits.h>
28 #include <dali/public-api/math/math-utils.h>
29
30 /**
31  * @brief For DALi internal use, asserts are enabled in debug builds.
32  *
33  * For Application use, asserts can be enabled manually.
34  * @SINCE_1_0.0
35  */
36 #if defined( DEBUG_ENABLED )
37 #define ENABLE_VECTOR_ASSERTS
38 #endif
39
40 #if defined( ENABLE_VECTOR_ASSERTS )
41 #define DALI_ASSERT_VECTOR(cond) DALI_ASSERT_ALWAYS(cond)
42 #else
43 #define DALI_ASSERT_VECTOR(cond)
44 #endif
45
46 namespace Dali
47 {
48 /**
49  * @addtogroup dali_core_common
50  * @{
51  */
52
53 /**
54  * @brief Base class to handle the memory of simple vector.
55  *
56  * Memory layout is such that it has two std::size_t to hold the count
57  * and capacity of the vector. VectorBase::mData is adjusted so that it points to the
58  * beginning of the first real item so that iterating the items is quick.
59  * @SINCE_1_0.0
60  */
61 class DALI_IMPORT_API VectorBase
62 {
63 public: // Typedefs
64
65   typedef std::size_t SizeType;
66
67 protected: // Construction
68
69   /**
70    * @brief Default constructor. Does not allocate space.
71    * @SINCE_1_0.0
72    */
73   VectorBase();
74
75   /**
76    * @brief Destructor.
77    *
78    * Does not release the space. Derived class needs to call Release.
79    * Not virtual as this should not be called directly and we do not want
80    * a vtable for this class as it would unnecessarily increase size.
81    * @SINCE_1_0.0
82    */
83   ~VectorBase();
84
85 public: // API
86
87   /**
88    * @brief This method is inlined as it's needed frequently for Vector::End() iterator.
89    *
90    * @SINCE_1_0.0
91    * @return The count of elements in this vector
92    */
93   SizeType Count() const
94   {
95     SizeType items = 0u;
96     if( mData )
97     {
98       SizeType* metadata = reinterpret_cast< SizeType* >( mData );
99       items = *(metadata - 1u);
100     }
101     return items;
102   }
103
104   /**
105    * @brief Gets the count of elements in this vector.
106    * @SINCE_1_0.0
107    * @return The count of elements in this vector
108    */
109   SizeType Size() const
110   {
111     return Count();
112   }
113
114   /**
115    * @brief @ return if the vector is empty.
116    * @SINCE_1_0.0
117    * @return True if the count of elements is empty
118    */
119   bool Empty() const
120   {
121     return Count() == 0u;
122   }
123
124   /**
125    * @brief Gets the capacity of this vector.
126    * @SINCE_1_0.0
127    * @return The capacity of this vector
128    */
129   SizeType Capacity() const;
130
131   /**
132    * @brief Releases the data.
133    *
134    * Does not call destructors on objects held.
135    * @SINCE_1_0.0
136    */
137   void Release();
138
139 protected: // for Derived classes
140
141   /**
142    * @brief Helper to set the count.
143    *
144    * @SINCE_1_0.0
145    * @param[in] count Number of elements in the vector
146    */
147   void SetCount( SizeType count );
148
149   /**
150    * @brief Reserves space in the vector.
151    *
152    * @SINCE_1_0.0
153    * @param[in] count Count of elements to reserve
154    * @param[in] elementSize Size of a single element
155    */
156   void Reserve( SizeType count, SizeType elementSize );
157
158   /**
159    * @brief Copy a vector.
160    *
161    * @SINCE_1_0.0
162    * @param[in] vector Vector to copy from
163    * @param[in] elementSize Size of a single element
164    */
165   void Copy( const VectorBase& vector, SizeType elementSize );
166
167   /**
168    * @brief Swaps the contents of two vectors.
169    *
170    * @SINCE_1_0.0
171    * @param[in] vector Vector to swap with
172    */
173   void Swap( VectorBase& vector );
174
175   /**
176    * @brief Erases an element.
177    *
178    * Does not change capacity.
179    * @SINCE_1_0.0
180    * @param[in] address Address to erase from
181    * @param[in] elementSize Size to erase
182    * @pre Last element cannot be erased as there is nothing to move.
183    */
184   void Erase( char* address, SizeType elementSize );
185
186   /**
187    * @brief Erases a range of elements.
188    *
189    * Does not change capacity.
190    * @SINCE_1_0.0
191    * @param[in] first Address to the first element to be erased
192    * @param[in] last Address to the last element to be erased
193    * @param[in] elementSize Size of one of the elements to be erased
194    * @return Address pointing to the next element of the last one
195    */
196   char* Erase( char* first, char* last, SizeType elementSize );
197
198   /**
199    * @brief Copies a number of bytes from \e source to \e destination.
200    *
201    * \e source and \e destination must not overlap.
202    *
203    * @SINCE_1_0.0
204    * @param[in] destination Pointer to the destination address
205    * @param[in] source Pointer to the source address
206    * @param[in] numberOfBytes The number of bytes to be copied
207    */
208   void CopyMemory( char* destination, const char* source, size_t numberOfBytes );
209
210 private:
211
212   // not copiable as it does not know the size of elements
213   VectorBase( const VectorBase& ); ///< Undefined @SINCE_1_0.0
214   VectorBase& operator=( const VectorBase& ); ///< Undefined @SINCE_1_0.0
215
216 protected: // Data
217
218   void* mData; ///< Pointer to the data.
219
220 };
221
222 /**
223  * @brief Vector algorithm variant for trivial types.
224  *
225  * Trivial types do not need destructor or copy constructor called.
226  * @SINCE_1_0.0
227  */
228 template< bool IsTrivial >
229 class VectorAlgorithms : public VectorBase
230 {
231 protected: // API for deriving classes
232
233   typedef VectorBase::SizeType SizeType;
234
235   /**
236    * @brief Empty constructor.
237    * @SINCE_1_0.0
238    */
239   VectorAlgorithms()
240   { }
241
242   /**
243    * @brief Empty destructor.
244    * @SINCE_1_0.0
245    */
246   ~VectorAlgorithms()
247   { }
248
249   /**
250    * @brief Copy vector contents.
251    *
252    * @SINCE_1_0.0
253    * @param[in] rhs VectorBase object to copy from
254    * @param[in] elementSize Size of the content
255    */
256   void Copy( const VectorBase& rhs, SizeType elementSize )
257   {
258     if( rhs.Capacity() > 0u )
259     {
260       VectorBase::Copy( rhs, elementSize );
261     }
262     else
263     {
264       VectorBase::Release();
265     }
266   }
267
268   /**
269    * @brief Reserves space in the vector.
270    *
271    * @SINCE_1_0.0
272    * @param[in] count Count of elements to reserve
273    * @param[in] elementSize Size of a single element
274    */
275   void Reserve( SizeType count, SizeType elementSize )
276   {
277     VectorBase::Reserve( count, elementSize );
278   }
279
280   /**
281    * @brief Resizes the vector. Does not change capacity.
282    *
283    * @SINCE_1_0.0
284    * @param[in] count Count to resize to
285    * @param[in] elementSize Size of a single element
286    */
287   void Resize( SizeType count, SizeType elementSize )
288   {
289     // reserve will copy old elements as well
290     Reserve( count, elementSize );
291   }
292
293   /**
294    * @brief Clears the contents.
295    *
296    * For simple types, nothing to do.
297    * @SINCE_1_0.0
298    */
299   void Clear()
300   {
301     if( mData )
302     {
303       VectorBase::SetCount( 0u );
304     }
305   }
306
307   /**
308    * @brief Releases the vector.
309    * @SINCE_1_0.0
310    */
311   void Release()
312   {
313     VectorBase::Release();
314   }
315
316   /**
317    * @brief Erases an element. Does not change capacity.
318    *
319    * @SINCE_1_0.0
320    * @param[in] address Address to erase from
321    * @param[in] elementSize Size to erase
322    */
323   void Erase( char* address, SizeType elementSize )
324   {
325     VectorBase::Erase( address, elementSize );
326   }
327
328   /**
329    * @brief Erases a range of elements. Does not change capacity.
330    *
331    * @SINCE_1_0.0
332    * @param[in] first Address to the first element to be erased
333    * @param[in] last Address to the last element to be erased
334    * @param[in] elementSize Size of one of the elements to be erased
335    * @return Address pointing to the next element of the last one
336    */
337   char* Erase( char* first, char* last, SizeType elementSize )
338   {
339     return VectorBase::Erase( first, last, elementSize );
340   }
341
342   /**
343    * @brief Inserts the given elements into the vector.
344    *
345    * @SINCE_1_0.0
346    * @param[in] at Address where to insert the elements into the vector
347    * @param[in] from Address to the first element to be inserted
348    * @param[in] to Address to the last element to be inserted
349    * @param[in] elementSize Size of one of the elements to be inserted
350    */
351   void Insert( char* at, char* from, char* to, SizeType elementSize )
352   {
353     const SizeType size = to - from;
354     const SizeType count = Count();
355     const SizeType newCount = count + size / elementSize;
356
357     if( newCount > Capacity() )
358     {
359       // Calculate the at offset as the pointer is invalid after the Reserve() call.
360       std::size_t offset = at - reinterpret_cast<char*>( mData );
361
362       // need more space
363       Reserve( NextPowerOfTwo( newCount ), elementSize ); // reserve enough space to store at least the next power of two elements of the new required size.
364
365       // Set the new at pointer.
366       at = reinterpret_cast<char*>( mData ) + offset;
367     }
368     // set new count first as otherwise the debug assert will hit us
369     SetCount( newCount );
370
371     // Move current items to a new position inside the vector.
372     CopyMemory( at + size,
373                 at,
374                 ( reinterpret_cast<char*>( mData ) + count * elementSize ) - at );
375
376     // Copy the given items.
377     CopyMemory( at, from, size );
378   }
379 };
380
381 /**
382  * @brief Vector algorithm variant for complex types.
383  *
384  * Not yet supported so will lead to compile error
385  * as constructor and destructor are private.
386  * TODO add support for this variant.
387  * @SINCE_1_0.0
388  */
389 template<>
390 class VectorAlgorithms< false > : public VectorBase
391 {
392 private:
393   VectorAlgorithms()
394   { }
395   ~VectorAlgorithms()
396   { }
397 };
398
399 /**
400  * @brief Vector class with minimum space allocation when it's empty.
401  *
402  * @SINCE_1_0.0
403  * @param type The type of the data that the vector holds
404  */
405 template< class T, bool IsTrivialType = TypeTraits<T>::IS_TRIVIAL_TYPE == true >
406 class Vector : public VectorAlgorithms< IsTrivialType >
407 {
408 public: // API
409
410   /**
411    * @brief Type definitions.
412    * @SINCE_1_0.0
413    */
414   typedef VectorBase::SizeType SizeType; ///< Size type @SINCE_1_0.0
415   typedef T* Iterator;  ///< Most simple Iterator is a pointer @SINCE_1_0.0
416   typedef const T* ConstIterator; ///< Const iterator @SINCE_1_0.0
417   typedef T  ItemType; ///< Item type @SINCE_1_0.0
418
419   enum
420   {
421     BaseType = IsTrivialType
422   };
423
424   /**
425    * @brief Default constructor. Does not allocate any space.
426    * @SINCE_1_0.0
427    */
428   Vector()
429   { }
430
431   /**
432    * @brief Destructor. Releases the allocated space.
433    * @SINCE_1_0.0
434    */
435   ~Vector()
436   {
437     Release();
438   }
439
440   /**
441    * @brief Copy constructor.
442    *
443    * @SINCE_1_0.0
444    * @param[in] vector Vector to copy from
445    */
446   Vector( const Vector& vector )
447   {
448     // reuse assignment
449     operator=( vector );
450   }
451
452   /**
453    * @brief Assignment operator.
454    *
455    * @SINCE_1_0.0
456    * @param[in] vector Vector to assign from
457    * @return Reference to self for chaining
458    */
459   Vector& operator=( const Vector& vector )
460   {
461     if( this != &vector )
462     {
463       VectorAlgorithms<BaseType>::Copy( vector, sizeof( ItemType ) );
464     }
465     return *this;
466   }
467
468   /**
469    * @brief Iterator to the beginning of the data.
470    * @SINCE_1_0.0
471    * @return Iterator to the beginning of the data
472    */
473   Iterator Begin() const
474   {
475     ItemType* address = reinterpret_cast<ItemType*>( VectorBase::mData );
476     return address;
477   }
478
479   /**
480    * @brief Iterator to the end of the data (one past last element).
481    * @SINCE_1_0.0
482    * @return Iterator to the end of the data (one past last element)
483    */
484   Iterator End() const
485   {
486     ItemType* address = reinterpret_cast<ItemType*>( VectorBase::mData );
487     address += VectorBase::Count();
488     return address;
489   }
490
491   /**
492    * @brief Subscript operator.
493    * @SINCE_1_0.0
494    * @param[in] index Index of the element
495    * @return Reference to the element for given index
496    * @pre Index must be in the vector's range.
497    */
498   ItemType& operator[]( SizeType index )
499   {
500     // reuse the const version
501     return const_cast< ItemType& >( const_cast< const Vector< ItemType >& >( *this )[ index ] );
502   }
503
504   /**
505    * @brief Subscript operator.
506    * @SINCE_1_0.0
507    * @param[in] index Index of the element
508    * @return Reference to the element for given index
509    * @pre Index must be in the vector's range.
510    */
511   const ItemType& operator[]( SizeType index ) const
512   {
513     DALI_ASSERT_VECTOR( VectorBase::mData && "Vector is empty" );
514     DALI_ASSERT_VECTOR( index < VectorBase::Count() && "Index out of bounds" );
515     ItemType* address = reinterpret_cast<ItemType*>( VectorBase::mData );
516     address += index;
517     return *address;
518   }
519
520   /**
521    * @brief Pushes back an element to the vector.
522    *
523    * The underlying storage may be reallocated to provide space.
524    * If this occurs, all pre-existing pointers into the vector will
525    * become invalid.
526    *
527    * @SINCE_1_0.0
528    * @param[in] element Element to be added
529    */
530   void PushBack( const ItemType& element )
531   {
532     const SizeType count = VectorBase::Count();
533     const SizeType newCount = count + 1u;
534     const SizeType capacity = VectorBase::Capacity();
535     if( newCount > capacity )
536     {
537       // need more space
538       Reserve( newCount << 1u ); // reserve double the current count
539     }
540     // set new count first as otherwise the debug assert will hit us
541     VectorBase::SetCount( newCount );
542     operator[]( count ) = element;
543   }
544
545   /**
546    * @brief Inserts an element to the vector.
547    *
548    * Elements after \e at are moved one position to the right.
549    *
550    * The underlying storage may be reallocated to provide space.
551    * If this occurs, all pre-existing pointers into the vector will
552    * become invalid.
553    *
554    * @SINCE_1_0.0
555    * @param[in] at Iterator where to insert the elements into the vector
556    * @param[in] element An element to be added
557    * @pre Iterator at must be in the vector's range ( Vector::Begin(), Vector::End() ).
558    */
559   void Insert( Iterator at, const ItemType& element )
560   {
561     DALI_ASSERT_VECTOR( ( at <= End() ) && ( at >= Begin() ) && "Iterator not inside vector" );
562     const SizeType size = sizeof( ItemType );
563     char* address = const_cast<char*>( reinterpret_cast<const char*>( &element ) );
564     VectorAlgorithms<BaseType>::Insert( reinterpret_cast< char* >( at ),
565                                         address,
566                                         address + size,
567                                         size );
568   }
569
570   /**
571    * @brief Inserts the given elements into the vector.
572    *
573    * Elements after \e at are moved the number of given elements positions to the right.
574    *
575    * The underlying storage may be reallocated to provide space.
576    * If this occurs, all pre-existing pointers into the vector will
577    * become invalid.
578    *
579    * @SINCE_1_0.0
580    * @param[in] at Iterator where to insert the elements into the vector
581    * @param[in] from Iterator to the first element to be inserted
582    * @param[in] to Iterator to the last element to be inserted
583    * @pre Iterator \e at must be in the vector's range ( Vector::Begin(), Vector::End() ).
584    * @pre Iterators \e from and \e to must be valid iterators.
585    * @pre Iterator \e from must not be grater than Iterator \e to.
586    *
587    */
588   void Insert( Iterator at, Iterator from, Iterator to )
589   {
590     DALI_ASSERT_VECTOR( ( at <= End() ) && ( at >= Begin() ) && "Iterator not inside vector" );
591     DALI_ASSERT_VECTOR( ( from <= to ) && "from address can't be greater than to" );
592
593     if( from == to )
594     {
595       // nothing to copy.
596       return;
597     }
598
599     VectorAlgorithms<BaseType>::Insert( reinterpret_cast< char* >( at ),
600                                         reinterpret_cast< char* >( from ),
601                                         reinterpret_cast< char* >( to ),
602                                         sizeof( ItemType ) );
603   }
604
605   /**
606    * @brief Reserves space in the vector.
607    *
608    * Reserving less than current Capacity is a no-op.
609    * @SINCE_1_0.0
610    * @param[in] count Count of elements to reserve
611    */
612   void Reserve( SizeType count )
613   {
614     VectorAlgorithms<BaseType>::Reserve( count, sizeof( ItemType ) );
615   }
616
617   /**
618    * @brief Resizes the vector. Does not change capacity.
619    *
620    * @SINCE_1_0.0
621    * @param[in] count Count to resize to
622    */
623   void Resize( SizeType count )
624   {
625     ItemType item = ItemType();
626     Resize(count, item);
627   }
628
629   /**
630    * @brief Resizes the vector. Does not change capacity.
631    *
632    * @SINCE_1_0.0
633    * @param[in] count Count to resize to
634    * @param[in] item An item to insert to the new indices
635    */
636   void Resize( SizeType count, const ItemType& item )
637   {
638     const SizeType oldCount = VectorBase::Count();
639     if( count <= oldCount )
640     {
641       // getting smaller so just set count
642       VectorBase::SetCount( count );
643     }
644     else
645     {
646       // remember how many new items get added
647       SizeType newItems = count - oldCount;
648       Reserve( count );
649       for( ; newItems > 0u; --newItems )
650       {
651         PushBack( item );
652       }
653     }
654   }
655
656   /**
657    * @brief Erases an element.
658    *
659    * Does not change capacity. Other elements get moved.
660    *
661    * @SINCE_1_0.0
662    * @param[in] iterator Iterator pointing to the item to remove
663    * @return Iterator pointing to next element
664    * @pre Iterator \e iterator must be within the vector's range ( Vector::Begin(), Vector::End() - 1 ).
665    *
666    */
667   Iterator Erase( Iterator iterator )
668   {
669     DALI_ASSERT_VECTOR( (iterator < End()) && (iterator >= Begin()) && "Iterator not inside vector" );
670     if( iterator < ( End() - 1u ) )
671     {
672       VectorAlgorithms<BaseType>::Erase( reinterpret_cast< char* >( iterator ), sizeof( ItemType ) );
673     }
674     else
675     {
676       // just remove the element
677       Remove( iterator );
678     }
679     return iterator;
680   }
681
682   /**
683    * @brief Erases a range of elements.
684    *
685    * Does not change capacity. Other elements get moved.
686    *
687    * @SINCE_1_0.0
688    * @param[in] first Iterator to the first element to be erased
689    * @param[in] last Iterator to the last element to be erased
690    *
691    * @return Iterator pointing to the next element of the last one
692    * @pre Iterator \e first must be in the vector's range ( Vector::Begin(), Vector::End() ).
693    * @pre Iterator \e last must be in the vector's range ( Vector::Begin(), Vector::End() ).
694    * @pre Iterator \e first must not be grater than Iterator \e last.
695    *
696    */
697   Iterator Erase( Iterator first, Iterator last )
698   {
699     DALI_ASSERT_VECTOR( ( first <= End() ) && ( first >= Begin() ) && "Iterator not inside vector" );
700     DALI_ASSERT_VECTOR( ( last <= End() ) && ( last >= Begin() ) && "Iterator not inside vector" );
701     DALI_ASSERT_VECTOR( ( first <= last ) && "first iterator greater than last" );
702
703     Iterator nextElement;
704
705     if( last == End() )
706     {
707       // Erase up to the end.
708       VectorBase::SetCount( VectorBase::Count() - ( last - first ) );
709       nextElement = End();
710     }
711     else
712     {
713       nextElement = reinterpret_cast<Iterator>( VectorAlgorithms<BaseType>::Erase( reinterpret_cast< char* >( first ),
714                                                                                    reinterpret_cast< char* >( last ),
715                                                                                    sizeof( ItemType ) ) );
716     }
717
718     return nextElement;
719   }
720
721   /**
722    * @brief Removes an element.
723    *
724    * Does not maintain order. Swaps the element with end and
725    * decreases size by one.  This is much faster than Erase so use
726    * this in case order does not matter. Does not change capacity.
727    *
728    * @SINCE_1_0.0
729    * @param[in] iterator Iterator pointing to the item to remove
730    * @pre Iterator \e iterator must be in the vector's range ( Vector::Begin(), Vector::End() - 1 ).
731    *
732    */
733   void Remove( Iterator iterator )
734   {
735     DALI_ASSERT_VECTOR( (iterator < End()) && (iterator >= Begin()) && "Iterator not inside vector" );
736
737     Iterator last = End() - 1u;
738     if( last > iterator )
739     {
740       std::swap( *iterator, *last );
741     }
742     VectorBase::SetCount( VectorBase::Count() - 1u );
743   }
744
745   /**
746    * @brief Swaps the contents of two vectors.
747    *
748    * @SINCE_1_0.0
749    * @param[in] vector Vector to swap with
750    */
751   void Swap( Vector& vector )
752   {
753     VectorBase::Swap( vector );
754   }
755
756   /**
757    * @brief Clears the contents of the vector. Keeps its capacity.
758    * @SINCE_1_0.0
759    */
760   void Clear()
761   {
762     VectorAlgorithms<BaseType>::Clear();
763   }
764
765   /**
766    * @brief Releases the memory that the vector holds.
767    * @SINCE_1_0.0
768    */
769   void Release()
770   {
771     VectorAlgorithms<BaseType>::Release();
772   }
773 };
774
775 /**
776  * @}
777  */
778 } // namespace Dali
779
780 #endif /* __DALI_VECTOR_H__ */