Add missed doxygen documentation
[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 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 its 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 Release 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 Reserve 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 Swap 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 Erase an element.
177    *
178    * Does not change capacity.
179    * @SINCE_1_0.0
180    * @param[in] address Adress 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 Erase 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 Reserve 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 Resize 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 Clear 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 Release the vector.
309    * @SINCE_1_0.0
310    */
311   void Release()
312   {
313     VectorBase::Release();
314   }
315
316   /**
317    * @brief Erase 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 Erase 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 its empty.
401  *
402  * @SINCE_1_0.0
403  * @param 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 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 Push 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 Insert 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    * @pre Iterator at must be in the vector's range ( Vector::Begin(), Vector::End() ).
555    *
556    * @param[in] at Iterator where to insert the elements into the vector.
557    * @param[in] element An element to be added.
558    *@SINCE_1_0.0
559    */
560   void Insert( Iterator at, const ItemType& element )
561   {
562     DALI_ASSERT_VECTOR( ( at <= End() ) && ( at >= Begin() ) && "Iterator not inside vector" );
563     const SizeType size = sizeof( ItemType );
564     char* address = const_cast<char*>( reinterpret_cast<const char*>( &element ) );
565     VectorAlgorithms<BaseType>::Insert( reinterpret_cast< char* >( at ),
566                                         address,
567                                         address + size,
568                                         size );
569   }
570
571   /**
572    * @brief Inserts the given elements into the vector.
573    *
574    * Elements after \e at are moved the number of given elements positions to the right.
575    *
576    * The underlying storage may be reallocated to provide space.
577    * If this occurs, all pre-existing pointers into the vector will
578    * become invalid.
579    *
580    * @SINCE_1_0.0
581    * @param[in] at Iterator where to insert the elements into the vector.
582    * @param[in] from Iterator to the first element to be inserted.
583    * @param[in] to Iterator to the last element to be inserted.
584    * @pre Iterator \e at must be in the vector's range ( Vector::Begin(), Vector::End() ).
585    * @pre Iterators \e from and \e to must be valid iterators.
586    * @pre Iterator \e from must not be grater than Iterator \e to.
587    *
588    */
589   void Insert( Iterator at, Iterator from, Iterator to )
590   {
591     DALI_ASSERT_VECTOR( ( at <= End() ) && ( at >= Begin() ) && "Iterator not inside vector" );
592     DALI_ASSERT_VECTOR( ( from <= to ) && "from address can't be greater than to" );
593
594     if( from == to )
595     {
596       // nothing to copy.
597       return;
598     }
599
600     VectorAlgorithms<BaseType>::Insert( reinterpret_cast< char* >( at ),
601                                         reinterpret_cast< char* >( from ),
602                                         reinterpret_cast< char* >( to ),
603                                         sizeof( ItemType ) );
604   }
605
606   /**
607    * @brief Reserve space in the vector.
608    *
609    * Reserving less than current Capacity is a no-op.
610    * @SINCE_1_0.0
611    * @param[in] count Count of elements to reserve.
612    */
613   void Reserve( SizeType count )
614   {
615     VectorAlgorithms<BaseType>::Reserve( count, sizeof( ItemType ) );
616   }
617
618   /**
619    * @brief Resize the vector. Does not change capacity.
620    *
621    * @SINCE_1_0.0
622    * @param[in] count Count to resize to.
623    */
624   void Resize( SizeType count )
625   {
626     ItemType item = ItemType();
627     Resize(count, item);
628   }
629
630   /**
631    * @brief Resize the vector. Does not change capacity.
632    *
633    * @SINCE_1_0.0
634    * @param[in] count Count to resize to.
635    * @param[in] item An item to insert to the new indices.
636    */
637   void Resize( SizeType count, const ItemType& item )
638   {
639     const SizeType oldCount = VectorBase::Count();
640     if( count <= oldCount )
641     {
642       // getting smaller so just set count
643       VectorBase::SetCount( count );
644     }
645     else
646     {
647       // remember how many new items get added
648       SizeType newItems = count - oldCount;
649       Reserve( count );
650       for( ; newItems > 0u; --newItems )
651       {
652         PushBack( item );
653       }
654     }
655   }
656
657   /**
658    * @brief Erase an element.
659    *
660    * Does not change capacity. Other elements get moved.
661    *
662    * @SINCE_1_0.0
663    * @param[in] iterator Iterator pointing to item to remove.
664    * @return Iterator pointing to next element.
665    * @pre Iterator \e iterator must be within the vector's range ( Vector::Begin(), Vector::End() - 1 ).
666    *
667    */
668   Iterator Erase( Iterator iterator )
669   {
670     DALI_ASSERT_VECTOR( (iterator < End()) && (iterator >= Begin()) && "Iterator not inside vector" );
671     if( iterator < ( End() - 1u ) )
672     {
673       VectorAlgorithms<BaseType>::Erase( reinterpret_cast< char* >( iterator ), sizeof( ItemType ) );
674     }
675     else
676     {
677       // just remove the element
678       Remove( iterator );
679     }
680     return iterator;
681   }
682
683   /**
684    * @brief Erase a range of elements.
685    *
686    * Does not change capacity. Other elements get moved.
687    *
688    * @SINCE_1_0.0
689    * @param[in] first Iterator to the first element to be erased.
690    * @param[in] last Iterator to the last element to be erased.
691    *
692    * @return Iterator pointing to the next element of the last one.
693    * @pre Iterator \e first must be in the vector's range ( Vector::Begin(), Vector::End() ).
694    * @pre Iterator \e last must be in the vector's range ( Vector::Begin(), Vector::End() ).
695    * @pre Iterator \e first must not be grater than Iterator \e last.
696    *
697    */
698   Iterator Erase( Iterator first, Iterator last )
699   {
700     DALI_ASSERT_VECTOR( ( first <= End() ) && ( first >= Begin() ) && "Iterator not inside vector" );
701     DALI_ASSERT_VECTOR( ( last <= End() ) && ( last >= Begin() ) && "Iterator not inside vector" );
702     DALI_ASSERT_VECTOR( ( first <= last ) && "first iterator greater than last" );
703
704     Iterator nextElement;
705
706     if( last == End() )
707     {
708       // Erase up to the end.
709       VectorBase::SetCount( VectorBase::Count() - ( last - first ) );
710       nextElement = End();
711     }
712     else
713     {
714       nextElement = reinterpret_cast<Iterator>( VectorAlgorithms<BaseType>::Erase( reinterpret_cast< char* >( first ),
715                                                                                    reinterpret_cast< char* >( last ),
716                                                                                    sizeof( ItemType ) ) );
717     }
718
719     return nextElement;
720   }
721
722   /**
723    * @brief Removes an element.
724    *
725    * Does not maintain order.  Swaps the element with end and
726    * decreases size by one.  This is much faster than Erase so use
727    * this in case order does not matter. Does not change capacity.
728    *
729    * @SINCE_1_0.0
730    * @param[in] iterator Iterator pointing to item to remove.
731    * @pre Iterator \e iterator must be in the vector's range ( Vector::Begin(), Vector::End() - 1 ).
732    *
733    */
734   void Remove( Iterator iterator )
735   {
736     DALI_ASSERT_VECTOR( (iterator < End()) && (iterator >= Begin()) && "Iterator not inside vector" );
737
738     Iterator last = End() - 1u;
739     if( last > iterator )
740     {
741       std::swap( *iterator, *last );
742     }
743     VectorBase::SetCount( VectorBase::Count() - 1u );
744   }
745
746   /**
747    * @brief Swap the contents of two vectors.
748    *
749    * @SINCE_1_0.0
750    * @param[in] vector Vector to swap with.
751    */
752   void Swap( Vector& vector )
753   {
754     VectorBase::Swap( vector );
755   }
756
757   /**
758    * @brief Clear the contents of the vector. Keeps its capacity.
759    * @SINCE_1_0.0
760    */
761   void Clear()
762   {
763     VectorAlgorithms<BaseType>::Clear();
764   }
765
766   /**
767    * @brief Release the memory that the vector holds.
768    * @SINCE_1_0.0
769    */
770   void Release()
771   {
772     VectorAlgorithms<BaseType>::Release();
773   }
774 };
775
776 /**
777  * @}
778  */
779 } // namespace Dali
780
781 #endif /* __DALI_VECTOR_H__ */