Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

issue #2790: Adds comments for Vector<T>. 

Signed-off-by: James Chen <jianhua.chen@cocos2d-x.org>
This commit is contained in:
James Chen 2013-12-12 14:22:49 +08:00
parent 3fc9c93102
commit 93bd45cefd
1 changed files with 95 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
cocos/base/CCVector.h
View File

@ -71,7 +71,7 @@ public:
}
/** creates an emptry Vector */
/** Constructor with a capacity */
explicit Vector<T>(int capacity)
: _data()
{
@ -79,12 +79,14 @@ public:
reserve(capacity);
}
/** Destructor */
~Vector<T>()
{
CCLOGINFO("In the destructor of Vector.");
clear();
}
/** Copy constructor */
Vector<T>(const Vector<T>& other)
{
CCLOGINFO("In the copy constructor!");
@ -99,6 +101,7 @@ public:
_data = std::move(other._data);
}
/** Copy assignment operator */
Vector<T>& operator=(const Vector<T>& other)
{
CCLOGINFO("In the copy assignment operator!");
@ -108,6 +111,7 @@ public:
return *this;
}
/** Move assignment operator */
Vector<T>& operator=(Vector<T>&& 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<int>(_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<T>::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<T> &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<T>& 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<void(T)>& 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<void(T)>& 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<void(T)>& 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<void(T)>& 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<bool(T, T)>& 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){