X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fcommon%2Fdali-vector.h;h=8422677013cdbb42a8689665316f7c521c2fcc23;hb=ef33338ef8e96ffcbc0131bd54aed039363325ab;hp=82bb898aa462389239a1cfe61973f1b16073fde5;hpb=199d46a42f943543a9d43cc3166a0d8b7cf63fd4;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/common/dali-vector.h b/dali/public-api/common/dali-vector.h old mode 100644 new mode 100755 index 82bb898..8422677 --- a/dali/public-api/common/dali-vector.h +++ b/dali/public-api/common/dali-vector.h @@ -2,7 +2,7 @@ #define __DALI_VECTOR_H__ /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2017 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,12 +24,14 @@ // INTERNAL INCLUDES #include +#include #include /** - * @brief For DALi internal use asserts are enabled in debug builds. + * @brief For DALi internal use, asserts are enabled in debug builds. * - * For Application use asserts can be enabled manually. + * For Application use, asserts can be enabled manually. + * @SINCE_1_0.0 */ #if defined( DEBUG_ENABLED ) #define ENABLE_VECTOR_ASSERTS @@ -43,13 +45,18 @@ namespace Dali { +/** + * @addtogroup dali_core_common + * @{ + */ /** * @brief Base class to handle the memory of simple vector. * * Memory layout is such that it has two std::size_t to hold the count - * and capacity of the vector. mData is adjusted so that it points to the + * and capacity of the vector. VectorBase::mData is adjusted so that it points to the * beginning of the first real item so that iterating the items is quick. + * @SINCE_1_0.0 */ class DALI_IMPORT_API VectorBase { @@ -61,6 +68,7 @@ protected: // Construction /** * @brief Default constructor. Does not allocate space. + * @SINCE_1_0.0 */ VectorBase(); @@ -68,17 +76,19 @@ protected: // Construction * @brief Destructor. * * Does not release the space. Derived class needs to call Release. - * Not virtual as should not be called directly and we do not want + * Not virtual as this should not be called directly and we do not want * a vtable for this class as it would unnecessarily increase size. + * @SINCE_1_0.0 */ ~VectorBase(); public: // API /** - * @brief This method is inlined as its needed frequently for End() iterator. + * @brief This method is inlined as it's needed frequently for Vector::End() iterator. * - * @return The count of elements in this vector. + * @SINCE_1_0.0 + * @return The count of elements in this vector */ SizeType Count() const { @@ -92,7 +102,9 @@ public: // API } /** - * @return The count of elements in this vector. + * @brief Gets the count of elements in this vector. + * @SINCE_1_0.0 + * @return The count of elements in this vector */ SizeType Size() const { @@ -100,14 +112,27 @@ public: // API } /** - * @return The capacity of this vector. + * @brief @ return if the vector is empty. + * @SINCE_1_0.0 + * @return True if the count of elements is empty + */ + bool Empty() const + { + return Count() == 0u; + } + + /** + * @brief Gets the capacity of this vector. + * @SINCE_1_0.0 + * @return The capacity of this vector */ SizeType Capacity() const; /** - * @brief Release the data. + * @brief Releases the data. * * Does not call destructors on objects held. + * @SINCE_1_0.0 */ void Release(); @@ -116,70 +141,77 @@ protected: // for Derived classes /** * @brief Helper to set the count. * - * @param count Number of elements in the vector. + * @SINCE_1_0.0 + * @param[in] count Number of elements in the vector */ void SetCount( SizeType count ); /** - * @brief Reserve space in the vector. + * @brief Reserves space in the vector. * - * @param count of elements to reserve. - * @param elementSize of a single element. + * @SINCE_1_0.0 + * @param[in] count Count of elements to reserve + * @param[in] elementSize Size of a single element */ void Reserve( SizeType count, SizeType elementSize ); /** * @brief Copy a vector. * - * @param vector Vector to copy from. - * @param elementSize of a single element. + * @SINCE_1_0.0 + * @param[in] vector Vector to copy from + * @param[in] elementSize Size of a single element */ void Copy( const VectorBase& vector, SizeType elementSize ); /** - * @brief Swap the contents of two vectors. + * @brief Swaps the contents of two vectors. * - * @param vector Vector to swap with. + * @SINCE_1_0.0 + * @param[in] vector Vector to swap with */ void Swap( VectorBase& vector ); /** - * @brief Erase an element. + * @brief Erases an element. * * Does not change capacity. - * @pre last element cannot be erased as there is nothing to move. - * @param address to erase from. - * @param elementSize to erase. + * @SINCE_1_0.0 + * @param[in] address Address to erase from + * @param[in] elementSize Size to erase + * @pre Last element cannot be erased as there is nothing to move. */ void Erase( char* address, SizeType elementSize ); /** - * @brief Erase a range of elements. + * @brief Erases a range of elements. * * Does not change capacity. - * @param[in] first Address to the first element to be erased. - * @param[in] last Address to the last element to be erased. - * @param[in] elementSize Size of one of the elements to be erased. - * @return address pointing to the next element of the last one. + * @SINCE_1_0.0 + * @param[in] first Address to the first element to be erased + * @param[in] last Address to the last element to be erased + * @param[in] elementSize Size of one of the elements to be erased + * @return Address pointing to the next element of the last one */ char* Erase( char* first, char* last, SizeType elementSize ); /** - * Copies a number of bytes from \e source to \e destination. + * @brief Copies a number of bytes from \e source to \e destination. * * \e source and \e destination must not overlap. * - * @param[in] destination Pointer to the destination address. - * @param[in] source Pointer to the source address. - * @param[in] numberOfBytes The number of bytes to be copied. + * @SINCE_1_0.0 + * @param[in] destination Pointer to the destination address + * @param[in] source Pointer to the source address + * @param[in] numberOfBytes The number of bytes to be copied */ void CopyMemory( char* destination, const char* source, size_t numberOfBytes ); private: // not copiable as it does not know the size of elements - VectorBase( const VectorBase& ); ///< Undefined - VectorBase& operator=( const VectorBase& ); ///< Undefined + VectorBase( const VectorBase& ); ///< Undefined @SINCE_1_0.0 + VectorBase& operator=( const VectorBase& ); ///< Undefined @SINCE_1_0.0 protected: // Data @@ -191,6 +223,7 @@ protected: // Data * @brief Vector algorithm variant for trivial types. * * Trivial types do not need destructor or copy constructor called. + * @SINCE_1_0.0 */ template< bool IsTrivial > class VectorAlgorithms : public VectorBase @@ -201,12 +234,14 @@ protected: // API for deriving classes /** * @brief Empty constructor. + * @SINCE_1_0.0 */ VectorAlgorithms() { } /** * @brief Empty destructor. + * @SINCE_1_0.0 */ ~VectorAlgorithms() { } @@ -214,8 +249,9 @@ protected: // API for deriving classes /** * @brief Copy vector contents. * - * @param rhs to copy from. - * @param elementSize of the content. + * @SINCE_1_0.0 + * @param[in] rhs VectorBase object to copy from + * @param[in] elementSize Size of the content */ void Copy( const VectorBase& rhs, SizeType elementSize ) { @@ -230,10 +266,11 @@ protected: // API for deriving classes } /** - * @brief Reserve space in the vector. + * @brief Reserves space in the vector. * - * @param count of elements to reserve. - * @param elementSize of a single element. + * @SINCE_1_0.0 + * @param[in] count Count of elements to reserve + * @param[in] elementSize Size of a single element */ void Reserve( SizeType count, SizeType elementSize ) { @@ -241,10 +278,11 @@ protected: // API for deriving classes } /** - * @brief Resize the vector. Does not change capacity. + * @brief Resizes the vector. Does not change capacity. * - * @param count to resize to. - * @param elementSize of a single element. + * @SINCE_1_0.0 + * @param[in] count Count to resize to + * @param[in] elementSize Size of a single element */ void Resize( SizeType count, SizeType elementSize ) { @@ -253,9 +291,10 @@ protected: // API for deriving classes } /** - * @brief Clear the contents. + * @brief Clears the contents. * - * For simple types nothing to do. + * For simple types, nothing to do. + * @SINCE_1_0.0 */ void Clear() { @@ -266,7 +305,8 @@ protected: // API for deriving classes } /** - * @brief Release the vector. + * @brief Releases the vector. + * @SINCE_1_0.0 */ void Release() { @@ -274,10 +314,11 @@ protected: // API for deriving classes } /** - * @brief Erase an element. Does not change capacity. + * @brief Erases an element. Does not change capacity. * - * @param address to erase from. - * @param elementSize to erase. + * @SINCE_1_0.0 + * @param[in] address Address to erase from + * @param[in] elementSize Size to erase */ void Erase( char* address, SizeType elementSize ) { @@ -285,12 +326,13 @@ protected: // API for deriving classes } /** - * @brief Erase a range of elements. Does not change capacity. + * @brief Erases a range of elements. Does not change capacity. * - * @param[in] first Address to the first element to be erased. - * @param[in] last Address to the last element to be erased. - * @param[in] elementSize Size of one of the elements to be erased. - * @return address pointing to the next element of the last one. + * @SINCE_1_0.0 + * @param[in] first Address to the first element to be erased + * @param[in] last Address to the last element to be erased + * @param[in] elementSize Size of one of the elements to be erased + * @return Address pointing to the next element of the last one */ char* Erase( char* first, char* last, SizeType elementSize ) { @@ -300,10 +342,11 @@ protected: // API for deriving classes /** * @brief Inserts the given elements into the vector. * - * @param[in] at Address where to insert the elements into the vector. - * @param[in] from Address to the first element to be inserted. - * @param[in] to Address to the last element to be inserted. - * @param[in] elementSize Size of one of the elements to be inserted. + * @SINCE_1_0.0 + * @param[in] at Address where to insert the elements into the vector + * @param[in] from Address to the first element to be inserted + * @param[in] to Address to the last element to be inserted + * @param[in] elementSize Size of one of the elements to be inserted */ void Insert( char* at, char* from, char* to, SizeType elementSize ) { @@ -341,6 +384,7 @@ protected: // API for deriving classes * Not yet supported so will lead to compile error * as constructor and destructor are private. * TODO add support for this variant. + * @SINCE_1_0.0 */ template<> class VectorAlgorithms< false > : public VectorBase @@ -353,36 +397,44 @@ private: }; /** - * @brief Vector class with minimum space allocation when its empty. + * @brief Vector class with minimum space allocation when it's empty. * - * @param type of the data that the vector holds. + * @SINCE_1_0.0 + * @param type The type of the data that the vector holds */ -template< class T, bool IsTrivialType = __has_trivial_destructor(T) && __has_trivial_copy(T) > +template< class T, bool IsTrivialType = TypeTraits::IS_TRIVIAL_TYPE == true > class Vector : public VectorAlgorithms< IsTrivialType > { public: // API /** * @brief Type definitions. + * @SINCE_1_0.0 */ - typedef VectorBase::SizeType SizeType; - typedef T* Iterator; ///< Most simple Iterator is a pointer - typedef const T* ConstIterator; - typedef T ItemType; + typedef VectorBase::SizeType SizeType; ///< Size type @SINCE_1_0.0 + typedef T* Iterator; ///< Most simple Iterator is a pointer @SINCE_1_0.0 + typedef const T* ConstIterator; ///< Const iterator @SINCE_1_0.0 + typedef T ItemType; ///< Item type @SINCE_1_0.0 + /** + * @brief Enumeration for BaseType. + * @SINCE_1_0.0 + */ enum { - BaseType = IsTrivialType + BaseType = IsTrivialType ///< @SINCE_1_0.0 }; /** * @brief Default constructor. Does not allocate any space. + * @SINCE_1_0.0 */ Vector() { } /** * @brief Destructor. Releases the allocated space. + * @SINCE_1_0.0 */ ~Vector() { @@ -392,7 +444,8 @@ public: // API /** * @brief Copy constructor. * - * @param vector Vector to copy from. + * @SINCE_1_0.0 + * @param[in] vector Vector to copy from */ Vector( const Vector& vector ) { @@ -403,8 +456,9 @@ public: // API /** * @brief Assignment operator. * - * @param vector Vector to assign from. - * @return reference to self for chaining. + * @SINCE_1_0.0 + * @param[in] vector Vector to assign from + * @return Reference to self for chaining */ Vector& operator=( const Vector& vector ) { @@ -416,7 +470,9 @@ public: // API } /** - * @return Iterator to the beginning of the data. + * @brief Iterator to the beginning of the data. + * @SINCE_1_0.0 + * @return Iterator to the beginning of the data */ Iterator Begin() const { @@ -425,7 +481,9 @@ public: // API } /** - * @return Iterator to the end of the data (one past last element). + * @brief Iterator to the end of the data (one past last element). + * @SINCE_1_0.0 + * @return Iterator to the end of the data (one past last element) */ Iterator End() const { @@ -435,9 +493,31 @@ public: // API } /** - * @pre index must be in the vector's range. - * @param index of the element. - * @return reference to the element for given index. + * Support for C++11 Range-based for loop: for( item : container ). + * @SINCE_1_2.60 + * @return The start iterator + */ + Iterator begin() const + { + return Begin(); + } + + /** + * Support for C++11 Range-based for loop: for( item : container ). + * @SINCE_1_2.60 + * @return The end iterator + */ + Iterator end() const + { + return End(); + } + + /** + * @brief Subscript operator. + * @SINCE_1_0.0 + * @param[in] index Index of the element + * @return Reference to the element for given index + * @pre Index must be in the vector's range. */ ItemType& operator[]( SizeType index ) { @@ -446,9 +526,11 @@ public: // API } /** - * @pre index must be in the vector's range. - * @param index of the element. - * @return reference to the element for given index. + * @brief Subscript operator. + * @SINCE_1_0.0 + * @param[in] index Index of the element + * @return Reference to the element for given index + * @pre Index must be in the vector's range. */ const ItemType& operator[]( SizeType index ) const { @@ -460,13 +542,14 @@ public: // API } /** - * @brief Push back an element to the vector. + * @brief Pushes back an element to the vector. * * The underlying storage may be reallocated to provide space. * If this occurs, all pre-existing pointers into the vector will * become invalid. * - * @param[in] element to be added. + * @SINCE_1_0.0 + * @param[in] element Element to be added */ void PushBack( const ItemType& element ) { @@ -484,7 +567,7 @@ public: // API } /** - *@brief Insert an element to the vector. + * @brief Inserts an element to the vector. * * Elements after \e at are moved one position to the right. * @@ -492,10 +575,10 @@ public: // API * If this occurs, all pre-existing pointers into the vector will * become invalid. * + * @SINCE_1_0.0 + * @param[in] at Iterator where to insert the elements into the vector + * @param[in] element An element to be added * @pre Iterator at must be in the vector's range ( Vector::Begin(), Vector::End() ). - * - * @param[in] at Iterator where to insert the elements into the vector. - * @param[in] element to be added. */ void Insert( Iterator at, const ItemType& element ) { @@ -517,13 +600,14 @@ public: // API * If this occurs, all pre-existing pointers into the vector will * become invalid. * + * @SINCE_1_0.0 + * @param[in] at Iterator where to insert the elements into the vector + * @param[in] from Iterator to the first element to be inserted + * @param[in] to Iterator to the last element to be inserted * @pre Iterator \e at must be in the vector's range ( Vector::Begin(), Vector::End() ). * @pre Iterators \e from and \e to must be valid iterators. * @pre Iterator \e from must not be grater than Iterator \e to. * - * @param[in] at Iterator where to insert the elements into the vector. - * @param[in] from Iterator to the first element to be inserted. - * @param[in] to Iterator to the last element to be inserted. */ void Insert( Iterator at, Iterator from, Iterator to ) { @@ -543,10 +627,11 @@ public: // API } /** - * @brief Reserve space in the vector. + * @brief Reserves space in the vector. * * Reserving less than current Capacity is a no-op. - * @param count of elements to reserve. + * @SINCE_1_0.0 + * @param[in] count Count of elements to reserve */ void Reserve( SizeType count ) { @@ -554,12 +639,25 @@ public: // API } /** - * @brief Resize the vector. Does not change capacity. + * @brief Resizes the vector. Does not change capacity. * - * @param count to resize to. - * @param item to insert to the new indices. + * @SINCE_1_0.0 + * @param[in] count Count to resize to */ - void Resize( SizeType count, ItemType item = ItemType() ) + void Resize( SizeType count ) + { + ItemType item = ItemType(); + Resize(count, item); + } + + /** + * @brief Resizes the vector. Does not change capacity. + * + * @SINCE_1_0.0 + * @param[in] count Count to resize to + * @param[in] item An item to insert to the new indices + */ + void Resize( SizeType count, const ItemType& item ) { const SizeType oldCount = VectorBase::Count(); if( count <= oldCount ) @@ -580,14 +678,15 @@ public: // API } /** - * @brief Erase an element. + * @brief Erases an element. * * Does not change capacity. Other elements get moved. * + * @SINCE_1_0.0 + * @param[in] iterator Iterator pointing to the item to remove + * @return Iterator pointing to next element * @pre Iterator \e iterator must be within the vector's range ( Vector::Begin(), Vector::End() - 1 ). * - * @param iterator Iterator pointing to item to remove. - * @return Iterator pointing to next element. */ Iterator Erase( Iterator iterator ) { @@ -605,18 +704,19 @@ public: // API } /** - * @brief Erase a range of elements. + * @brief Erases a range of elements. * * Does not change capacity. Other elements get moved. * + * @SINCE_1_0.0 + * @param[in] first Iterator to the first element to be erased + * @param[in] last Iterator to the last element to be erased + * + * @return Iterator pointing to the next element of the last one * @pre Iterator \e first must be in the vector's range ( Vector::Begin(), Vector::End() ). * @pre Iterator \e last must be in the vector's range ( Vector::Begin(), Vector::End() ). * @pre Iterator \e first must not be grater than Iterator \e last. * - * @param[in] first Iterator to the first element to be erased. - * @param[in] last Iterator to the last element to be erased. - * - * @return Iterator pointing to the next element of the last one. */ Iterator Erase( Iterator first, Iterator last ) { @@ -645,13 +745,14 @@ public: // API /** * @brief Removes an element. * - * Does not maintain order. Swaps the element with end and + * Does not maintain order. Swaps the element with end and * decreases size by one. This is much faster than Erase so use * this in case order does not matter. Does not change capacity. * + * @SINCE_1_0.0 + * @param[in] iterator Iterator pointing to the item to remove * @pre Iterator \e iterator must be in the vector's range ( Vector::Begin(), Vector::End() - 1 ). * - * @param iterator Iterator pointing to item to remove. */ void Remove( Iterator iterator ) { @@ -666,9 +767,10 @@ public: // API } /** - * @brief Swap the contents of two vectors. + * @brief Swaps the contents of two vectors. * - * @param vector Vector to swap with. + * @SINCE_1_0.0 + * @param[in] vector Vector to swap with */ void Swap( Vector& vector ) { @@ -676,7 +778,8 @@ public: // API } /** - * @brief Clear the contents of the vector. Keeps its capacity. + * @brief Clears the contents of the vector. Keeps its capacity. + * @SINCE_1_0.0 */ void Clear() { @@ -684,7 +787,8 @@ public: // API } /** - * @brief Release the memory that the vector holds. + * @brief Releases the memory that the vector holds. + * @SINCE_1_0.0 */ void Release() { @@ -692,6 +796,9 @@ public: // API } }; +/** + * @} + */ } // namespace Dali #endif /* __DALI_VECTOR_H__ */