diff --git a/cocos/base/CCVector.h b/cocos/base/CCVector.h index f049e4dd42..984e0a8314 100644 --- a/cocos/base/CCVector.h +++ b/cocos/base/CCVector.h @@ -71,7 +71,7 @@ public: } - /** creates an emptry Vector */ + /** Constructor with a capacity */ explicit Vector(int capacity) : _data() { @@ -79,12 +79,14 @@ public: reserve(capacity); } + /** Destructor */ ~Vector() { CCLOGINFO("In the destructor of Vector."); clear(); } + /** Copy constructor */ Vector(const Vector& other) { CCLOGINFO("In the copy constructor!"); @@ -99,6 +101,7 @@ public: _data = std::move(other._data); } + /** Copy assignment operator */ Vector& operator=(const Vector& other) { CCLOGINFO("In the copy assignment operator!"); @@ -108,6 +111,7 @@ public: return *this; } + /** Move assignment operator */ Vector& operator=(Vector&& other) { CCLOGINFO("In the move assignment operator!"); @@ -126,31 +130,49 @@ public: // return _data[index]; // } - /** Sets capacity of current array */ - void reserve(int capacity) + /** @brief Request a change in capacity + * @param capacity Minimum capacity for the vector. + * If n is greater than the current vector capacity, + * the function causes the container to reallocate its storage increasing its capacity to n (or greater). + */ + void reserve(int n) { - _data.reserve(capacity); + _data.reserve(n); } - /** Returns capacity of the array */ + /** @brief Returns the size of the storage space currently allocated for the vector, expressed in terms of elements. + * @note This capacity is not necessarily equal to the vector size. + * It can be equal or greater, with the extra space allowing to accommodate for growth without the need to reallocate on each insertion. + * @return The size of the currently allocated storage capacity in the vector, measured in terms of the number elements it can hold. + */ int capacity() const { return _data.capacity(); } - // Querying an Array - - /** Returns element count of the array */ + /** @brief Returns the number of elements in the vector. + * @note This is the number of actual objects held in the vector, which is not necessarily equal to its storage capacity. + * @return The number of elements in the container. + */ int size() const { return static_cast(_data.size()); } + /** @brief Returns whether the vector is empty (i.e. whether its size is 0). + * @note This function does not modify the container in any way. To clear the content of a vector, see Vector::clear. + */ bool empty() const { return _data.empty(); } + /** Returns the maximum number of elements that the vector can hold. */ + size_t max_size() const + { + return _data.max_size(); + } + /** Returns index of a certain object, return UINT_MAX if doesn't contain the object */ int getIndex(T object) const { @@ -161,6 +183,10 @@ public: return -1; } + /** @brief Find the object in the vector. + * @return Returns an iterator to the first element in the range [first,last) that compares equal to val. + * If no such element is found, the function returns last. + */ const_iterator find(T object) const { return std::find(_data.begin(), _data.end(), object); @@ -171,25 +197,26 @@ public: return std::find(_data.begin(), _data.end(), object); } - /** Returns an element with a certain index */ + /** Returns the element at position 'index' in the vector. */ T at(int index) const { CCASSERT( index >= 0 && index < size(), "index out of range in getObjectAtIndex()"); return _data[index]; } + /** Returns the first element in the vector. */ T front() const { return _data.front(); } - /** Returns the last element of the array */ + /** Returns the last element of the vector. */ T back() const { return _data.back(); } - /** Returns a random element */ + /** Returns a random element of the vector. */ T getRandomObject() const { if (!_data.empty()) @@ -200,13 +227,13 @@ public: return nullptr; } - /** Returns a Boolean value that indicates whether object is present in array. */ + /** Returns a Boolean value that indicates whether object is present in vector. */ bool contains(T object) const { return( std::find(_data.begin(), _data.end(), object) != _data.end() ); } - /** returns true if the the arrays are equal */ + /** Returns true if the two vectors are equal */ bool equals(const Vector &other) { size_t s = this->size(); @@ -223,9 +250,13 @@ public: return true; } - // Adding Objects - - /** Add a certain object */ + // Adds objects + + /** @brief Adds a new element at the end of the vector, after its current last element. + * @note This effectively increases the container size by one, + * which causes an automatic reallocation of the allocated storage space + * if -and only if- the new vector size surpasses the current vector capacity. + */ void pushBack(T object) { CCASSERT(object != nullptr, "The object should not be nullptr"); @@ -233,7 +264,7 @@ public: object->retain(); } - /** Add all elements of an existing array */ + /** Inserts all elements of an existing vector */ void insert(const Vector& other) { for( auto it = other.begin(); it != other.end(); ++it ) { @@ -242,7 +273,12 @@ public: } } - /** Insert a certain object at a certain index */ + /** @brief Insert a certain object at a certain index + * @note The vector is extended by inserting new elements before the element at the specified 'index', + * effectively increasing the container size by the number of elements inserted. + * This causes an automatic reallocation of the allocated storage space + * if -and only if- the new vector size surpasses the current vector capacity. + */ void insert(int index, T object) { CCASSERT(index >= 0 && index <= size(), "Invalid index!"); @@ -251,9 +287,11 @@ public: object->retain(); } - // Removing Objects + // Removes Objects - /** Remove last object */ + /** Removes the last element in the vector, + * effectively reducing the container size by one, decrease the referece count of the deleted object. + */ void popBack() { CCASSERT(!_data.empty(), "no objects added"); @@ -262,7 +300,10 @@ public: last->release(); } - /** Remove a certain object */ + /** @brief Remove a certain object. + * @param object The object to be removed. + * @param toRelease Whether to decrease the referece count of the deleted object. + */ void erase(T object, bool toRelease = true) { CCASSERT(object != nullptr, "The object should not be nullptr"); @@ -273,7 +314,11 @@ public: object->release(); } - /** Removes an element with a certain index */ + /** @brief Removes from the vector with an iterator. + * @param position Iterator pointing to a single element to be removed from the vector. + * @return An iterator pointing to the new location of the element that followed the last element erased by the function call. + * This is the container end if the operation erased the last element in the sequence. + */ iterator erase(iterator position) { CCASSERT(position >= _data.begin() && position < _data.end(), "Invalid position!"); @@ -281,6 +326,12 @@ public: return _data.erase(position); } + /** @brief Removes from the vector with a range of elements ( [first, last) ). + * @param first The beginning of the range + * @param last The end of the range, the 'last' will not used, it's only for indicating the end of range. + * @return An iterator pointing to the new location of the element that followed the last element erased by the function call. + * This is the container end if the operation erased the last element in the sequence. + */ iterator erase(const_iterator first, const_iterator last) { for (auto iter = first; iter != last; ++iter) @@ -291,15 +342,22 @@ public: return _data.erase(first, last); } - void erase(int index) + /** @brief Removes from the vector with an index. + * @param index The index of the element to be removed from the vector. + * @return An iterator pointing to the new location of the element that followed the last element erased by the function call. + * This is the container end if the operation erased the last element in the sequence. + */ + iterator erase(int index) { CCASSERT(!_data.empty() && index >=0 && index < size(), "Invalid index!"); auto it = std::next( begin(), index ); (*it)->release(); - _data.erase(it); + return _data.erase(it); } - /** Removes all objects */ + /** @brief Removes all elements from the vector (which are destroyed), leaving the container with a size of 0. + * @note All the elements in the vector will be released (referece count will be decreased). + */ void clear() { for( auto it = std::begin(_data); it != std::end(_data); ++it ) { @@ -340,18 +398,19 @@ public: object->retain(); } - /** reverses the array */ + /** reverses the vector */ void reverse() { std::reverse( std::begin(_data), std::end(_data) ); } - /** Shrinks the array so the memory footprint corresponds with the number of items */ + /** Shrinks the vector so the memory footprint corresponds with the number of items */ void shrinkToFit() { _data.shrink_to_fit(); } + /** Traverses through the vector and applys the callback function for each element */ void forEach(const std::function& callback) { if (empty()) @@ -362,6 +421,7 @@ public: }); } + /** Traverses through the vector and applys the callback function for each element */ void forEach(const std::function& callback) const { if (empty()) @@ -372,6 +432,7 @@ public: }); } + /** Traverses through the vector in reversed order and applys the callback function for each element */ void forEachReverse(const std::function& callback) { if (empty()) @@ -382,6 +443,7 @@ public: }); } + /** Traverses through the vector in reversed order and applys the callback function for each element */ void forEachReverse(const std::function& callback) const { if (empty()) @@ -392,6 +454,11 @@ public: }); } + /** @brief Sorts all elements in the vector according the binary callback function. + * @param callback Binary function that accepts two elements in the vector as arguments, + * and returns a value convertible to bool. + * The value returned indicates whether the element passed as first argument is considered to go before the second in the specific strict weak ordering it defines. + */ void sort(const std::function& callback) { if (empty()) @@ -404,6 +471,7 @@ public: protected: + /** Retains all the objects in the vector */ void addRefForAllObjects() { std::for_each(_data.begin(), _data.end(), [](T obj){