From 6264336809a2cb630af74a42dbb094421de80dea Mon Sep 17 00:00:00 2001 From: James Chen Date: Thu, 12 Dec 2013 11:54:03 +0800 Subject: [PATCH 1/3] issue #2790: Updates comments for Map container. Signed-off-by: James Chen --- cocos/base/CCMap.h | 59 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/cocos/base/CCMap.h b/cocos/base/CCMap.h index 3c5566b196..5f2de4e9db 100644 --- a/cocos/base/CCMap.h +++ b/cocos/base/CCMap.h @@ -59,12 +59,14 @@ public: const_iterator cbegin() const { return _data.cbegin(); } const_iterator cend() const { return _data.cend(); } + /** Default constructor */ Map() : _data() { CCLOGINFO("In the default constructor of Map!"); } + /** Contructor with capacity */ explicit Map(int capacity) : _data() { @@ -72,6 +74,7 @@ public: _data.reserve(capacity); } + /** Copy constructor */ Map(const Map& other) { CCLOGINFO("In the copy constructor of Map!"); @@ -79,40 +82,50 @@ public: addRefForAllObjects(); } + /** Move constructor */ Map(Map&& other) { CCLOGINFO("In the move constructor of Map!"); _data = std::move(other._data); } + /** Destructor + * It will release all objects in map. + */ ~Map() { CCLOGINFO("In the destructor of Map!"); clear(); } - /** Sets capacity of current array */ + /** Sets capacity of the map */ void reserve(int capacity) { _data.reserve(capacity); } - /** Returns capacity of the array */ + /** Returns capacity of the map */ size_t capacity() const { return _data.capacity(); } + /** The number of elements in the map. */ size_t size() const { return _data.size(); } + /** Returns a bool value indicating whether the map container is empty, i.e. whether its size is 0. + * @note This function does not modify the content of the container in any way. + * To clear the content of an array object, member function unordered_map::clear exists. + */ bool empty() const { return _data.empty(); } + /** Returns all keys in the map */ std::vector keys() const { std::vector keys; @@ -127,6 +140,7 @@ public: return keys; } + /** Returns all keys that matches the object */ std::vector keys(V object) const { std::vector keys; @@ -142,6 +156,11 @@ public: return keys; } + /** @brief Returns a reference to the mapped value of the element with key k in the map. + * @note If key does not match the key of any element in the container, the function return nullptr. + * @param key Key value of the element whose mapped value is accessed. + * Member type K is the keys for the elements in the container. defined in Map as an alias of its first template parameter (Key). + */ const V at(const K& key) const { auto iter = _data.find(key); @@ -158,6 +177,13 @@ public: return nullptr; } + /** @brief Searches the container for an element with 'key' as key and returns an iterator to it if found, + * otherwise it returns an iterator to Map::end (the element past the end of the container). + * @param key Key to be searched for. + * Member type 'K' is the type of the keys for the elements in the container, + * defined in Map as an alias of its first template parameter (Key). + * + */ const_iterator find(const K& key) const { return _data.find(key); @@ -168,6 +194,11 @@ public: return _data.find(key); } + /** @brief Inserts new elements in the map. + * @note If the container has already contained the key, this function will erase the old pair(key, object) and insert the new pair. + * @param key The key to be inserted. + * @param object The object to be inserted. + */ void insert(const K& key, V object) { CCASSERT(object != nullptr, "Object is nullptr!"); @@ -176,11 +207,22 @@ public: object->retain(); } + /** @brief Removes an element with an iterator from the Map container. + * @param position Iterator pointing to a single element to be removed from the Map. + * Member type const_iterator is a forward iterator type. + */ iterator erase(const_iterator position) { + CCASSERT(position >= _data.begin() && position < _data.end(), ""); + position->second->release(); return _data.erase(position); } + /** @brief Removes an element with an iterator from the Map container. + * @param k Key of the element to be erased. + * Member type 'K' is the type of the keys for the elements in the container, + * defined in Map as an alias of its first template parameter (Key). + */ size_t erase(const K& k) { auto iter = _data.find(k); @@ -194,6 +236,9 @@ public: return 0; } + /** @brief Removes some elements with a vector which contains keys in the map. + * @param keys Keys of elements to be erased. + */ void erase(const std::vector& keys) { std::for_each(keys.cbegin(), keys.cend(), [this](const K& key){ @@ -201,6 +246,10 @@ public: }); } + /** All the elements in the Map container are dropped: + * their reference count will be decreased, and they are removed from the container, + * leaving it with a size of 0. Al + */ void clear() { for (auto iter = _data.cbegin(); iter != _data.cend(); ++iter) @@ -211,6 +260,9 @@ public: _data.clear(); } + /** @brief Gets a random object in the map + * @return Returns the random object if the map isn't empty, otherwise it returns nullptr. + */ V getRandomObject() const { if (!_data.empty()) @@ -246,6 +298,7 @@ public: // return _data.at(key); // } + /** Copy assignment operator */ Map& operator= ( const Map& other ) { CCLOGINFO("In the copy assignment operator of Map!"); @@ -255,6 +308,7 @@ public: return *this; } + /** Move assignment operator */ Map& operator= ( Map&& other ) { CCLOGINFO("In the move assignment operator of Map!"); @@ -264,6 +318,7 @@ public: protected: + /** Retains all the objects in the map */ void addRefForAllObjects() { for (auto iter = _data.begin(); iter != _data.end(); ++iter) From 3fc9c93102c5f16adbfa325d7ce07b13c9335890 Mon Sep 17 00:00:00 2001 From: James Chen Date: Thu, 12 Dec 2013 12:58:01 +0800 Subject: [PATCH 2/3] issue #2790: Comment fix for Map::clear. Signed-off-by: James Chen --- cocos/base/CCMap.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cocos/base/CCMap.h b/cocos/base/CCMap.h index 5f2de4e9db..e48ef19854 100644 --- a/cocos/base/CCMap.h +++ b/cocos/base/CCMap.h @@ -248,7 +248,7 @@ public: /** All the elements in the Map container are dropped: * their reference count will be decreased, and they are removed from the container, - * leaving it with a size of 0. Al + * leaving it with a size of 0. */ void clear() { From 93bd45cefd7d4d4818cda72f0bb01e267fbb0dc6 Mon Sep 17 00:00:00 2001 From: James Chen Date: Thu, 12 Dec 2013 14:22:49 +0800 Subject: [PATCH 3/3] issue #2790: Adds comments for Vector. Signed-off-by: James Chen --- cocos/base/CCVector.h | 122 ++++++++++++++++++++++++++++++++---------- 1 file changed, 95 insertions(+), 27 deletions(-) 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){