cocos2d-x节点（CCArray.h)API
本文来自http://blog.csdn.net/runaying ，引用必须注明出处！
cocos2d-x节点（CCArray.h)API
温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记
这个类非常常用,可以存储任何对象，它可以模拟 C的指针，
///\cocos2d-x-3.0alpha0\cocos2dx\cocoa
//这个类非常常用,可以存储任何对象，它可以模拟 C 的指针，
#ifndef __CCARRAY_H__
#define __CCARRAY_H__
#define CC_USE_ARRAY_VECTOR 0
#if CC_USE_ARRAY_VECTOR
#include <vector>
#include <algorithm>
#include "cocoa/CCObject.h"
#include "ccMacros.h"
#else
#include "support/data_support/ccCArray.h"
#endif
#if CC_USE_ARRAY_VECTOR
/**
* 一个来自RCBase类的引用计数管理指针
* 可以作为 C 指针使用
* Original code: http://www.codeproject.com/Articles/64111/Building-a-Quick-and-Handy-Reference-Counting-Clas //源代码
* License: http://www.codeproject.com/info/cpol10.aspx //许可
*/
template < class T >
class RCPtr
{
public:
//使用 C 指针的构造函数
//e.g. RCPtr< T > x = new T();
RCPtr(T* ptr = nullptr)
: _ptr(ptr)
{
if(ptr != nullptr) {ptr->retain();}
}
//Copy 构造函数
RCPtr(const RCPtr &ptr)
: _ptr(ptr._ptr)
{
// printf("Array: copy constructor: %p\n", this);
if(_ptr != NULL) {_ptr->retain();}
}
//Move 构造函数
RCPtr(RCPtr &&ptr)
: _ptr(ptr._ptr)
{
// printf("Array: Move Constructor: %p\n", this);
ptr._ptr = nullptr;
}
~RCPtr()
{
// printf("Array: Destructor: %p\n", this);
if(_ptr != nullptr) {_ptr->release();}
}
//分配一个指针
//e.g. x = new T();
RCPtr &operator=(T* ptr)
{
// printf("Array: operator= T*: %p\n", this);
//以下获取和释放操作必须执行
//按照这个顺序来处理 ptr == _ptr 的情况
//参阅 David Garlisch 的评论)
if(ptr != nullptr) {ptr->retain();}
if(_ptr != nullptr) {_ptr->release();}
_ptr = ptr;
return (*this);
}
//分配另一个 RCPtr
RCPtr &operator=(const RCPtr &ptr)
{
// printf("Array: operator= const&: %p\n", this);
return (*this) = ptr._ptr;
}
//Retrieve（检索）真实的指针
T* get() const
{
return _ptr;
}
//一些重载 operators 可以方便使用一个 RCPtr
//作为一个传统的 C 指针.
//如果没有这些 operators, 仍然可以使用但是透明度较低
//get() 方法来访问指针.
T* operator->() const {return _ptr;} //x->member
T &operator*() const {return *_ptr;} //*x, (*x).member
explicit operator T*() const {return _ptr;} //T* y = x;
explicit operator bool() const {return _ptr != nullptr;} //if(x) {/*x is not NULL*/}
bool operator==(const RCPtr &ptr) {return _ptr == ptr._ptr;}
bool operator==(const T *ptr) {return _ptr == ptr;}
private:
T *_ptr; //Actual pointer（真实的指针）
};
#endif // CC_USE_ARRAY_VECTOR
/**
* @addtogroup data_structures
* @{
*/
/** @def CCARRAY_FOREACH
一个用来遍历 Array 的宏. 他比 "fast enumeration" 接口还要快.
@since v0.99.4
*/
/*
In cocos2d-iphone 1.0.0, 这个 macro（宏） 已经更新；像这个:
#define CCARRAY_FOREACH(__array__, __object__) \
if (__array__ && __array__->data->num > 0) \
for(id *__arr__ = __array__->data->arr, *end = __array__->data->arr + __array__->data->num-1; \
__arr__ <= end && ((__object__ = *__arr__) != nil || true); \
__arr__++)
我发现他不能在 C++ 里面工作.所以他看起来和 1.0.0-rc3 版本一样. ---By Bin
*/
#if CC_USE_ARRAY_VECTOR
#define CCARRAY_FOREACH(__array__, __object__) \
if (__array__) \
for( auto __it__ = (__array__)->data.begin(); \
__it__ != (__array__)->data.end() && ((__object__) = __it__->get()) != nullptr; \
++__it__)
#define CCARRAY_FOREACH_REVERSE(__array__, __object__) \
if (__array__) \
for( auto __it__ = (__array__)->data.rbegin(); \
__it__ != (__array__)->data.rend() && ((__object__) = __it__->get()) != nullptr; \
++__it__ )
#define CCARRAY_VERIFY_TYPE(__array__, __type__) void(0)
#else // ! CC_USE_ARRAY_VECTOR --------------------------
#define CCARRAY_FOREACH(__array__, __object__) \
if ((__array__) && (__array__)->data->num > 0) \
for(Object** __arr__ = (__array__)->data->arr, **__end__ = (__array__)->data->arr + (__array__)->data->num-1; \
__arr__ <= __end__ && (((__object__) = *__arr__) != NULL/* || true*/); \
__arr__++)
#define CCARRAY_FOREACH_REVERSE(__array__, __object__) \
if ((__array__) && (__array__)->data->num > 0) \
for(Object** __arr__ = (__array__)->data->arr + (__array__)->data->num-1, **__end__ = (__array__)->data->arr; \
__arr__ >= __end__ && (((__object__) = *__arr__) != NULL/* || true*/); \
__arr__--)
#if defined(COCOS2D_DEBUG) && (COCOS2D_DEBUG > 0)
#define CCARRAY_VERIFY_TYPE(__array__, __type__) \
do { \
if ((__array__) && (__array__)->data->num > 0) \
for(Object** __arr__ = (__array__)->data->arr, \
**__end__ = (__array__)->data->arr + (__array__)->data->num-1; __arr__ <= __end__; __arr__++) \
CCASSERT(dynamic_cast<__type__>(*__arr__), "element type is wrong!"); \
} while(false)
#else
#define CCARRAY_VERIFY_TYPE(__array__, __type__) void(0)
#endif
#endif // ! CC_USE_ARRAY_VECTOR
// Common defines ----------------------------------------------------------------------------------------------- //常见的定义
#define arrayMakeObjectsPerformSelector(pArray, func, elementType) \
do { \
if(pArray && pArray->count() > 0) \
{ \
Object* child; \
CCARRAY_FOREACH(pArray, child) \
{ \
elementType pNode = static_cast<elementType>(child); \
if(pNode) \
{ \
pNode->func(); \
} \
} \
} \
} \
while(false)
#define arrayMakeObjectsPerformSelectorWithObject(pArray, func, object, elementType) \
do { \
if(pArray && pArray->count() > 0) \
{ \
Object* child; \
CCARRAY_FOREACH(pArray, child) \
{ \
elementType pNode = static_cast<elementType>(child); \
if(pNode) \
{ \
pNode->func(object); \
} \
} \
} \
} \
while(false)
NS_CC_BEGIN
class CC_DLL Array : public Object, public Clonable
{
public:
/** 创建一个空的 array.默认容量是10
* @js NA
* @lua NA
*/
static Array* create();
/** 使用 objects 创建一个 array
* @js NA
*/
static Array* create(Object* object, ...) CC_REQUIRES_NULL_TERMINATION;
/** 使用 object 创建一个 array
* @js NA
*/
static Array* createWithObject(Object* object);
/** 使用指定容量创建一个 array
* @js NA
*/
static Array* createWithCapacity(int capacity);
/** 使用一个已经存在的 array 创建一个 array
* @js NA
*/
static Array* createWithArray(Array* otherArray);
/**
@brief 从 file 生成一个 array 指针
@param pFileName *.plist 文件的文件名
@return 从 file 生成的 array 指针
* @js NA
*/
static Array* createWithContentsOfFile(const char* pFileName);
/*
@brief 他和 arrayWithContentsOfFile() 的含义相同，但它不能自动释放，所以
调用者应该手动调用调用release（）。
* @js NA
* @lua NA
*/
static Array* createWithContentsOfFileThreadSafe(const char* pFileName);
/**
* @js NA
* @lua NA
*/
~Array();
/** 初始化 array
* @js NA
* @lua NA
*/
bool init();
/** 使用 object 初始化一个 array
* @js NA
* @lua NA
*/
bool initWithObject(Object* object);
/** 使用 objects 初始化一个 array
* @js NA
* @lua NA
*/
bool initWithObjects(Object* object, ...) CC_REQUIRES_NULL_TERMINATION;
/** 使用指定容量初始化一个 array
* @js NA
* @lua NA
*/
bool initWithCapacity(int capacity);
/** 使用一个已经存在的 array 创建一个 array
* @js NA
* @lua NA
*/
bool initWithArray(Array* otherArray);
// 查询 Array
/** Returns 这个 array 中元素的数量
* @js NA
*/
int count() const
{
#if CC_USE_ARRAY_VECTOR
return data.size();
#else
return data->num;
#endif
}
/** Returns 这个 array 的容量
* @js NA
*/
int capacity() const
{
#if CC_USE_ARRAY_VECTOR
return data.capacity();
#else
return data->max;
#endif
}
/** Returns 一个 certain（确定）对象的索引, return UINT_MAX 如果不包含这个对象返回
* @js NA
* @lua NA
*/
int getIndexOfObject(Object* object) const;
/**
* @js NA
*/
CC_DEPRECATED_ATTRIBUTE int indexOfObject(Object* object) const { return getIndexOfObject(object); }
/** Returns 返回 certain 索引对应的元素
* @js NA
* @lua NA
*/
Object* getObjectAtIndex(int index)
{
CCASSERT(index>=0 && index < count(), "index out of range in getObjectAtIndex()");
#if CC_USE_ARRAY_VECTOR
return data[index].get();
#else
return data->arr[index];
#endif
}
CC_DEPRECATED_ATTRIBUTE Object* objectAtIndex(int index) { return getObjectAtIndex(index); }
/** Returns 这个 array 的最后一个元素
* @js NA
*/
Object* getLastObject()
{
#if CC_USE_ARRAY_VECTOR
return data.back().get();
#else
if(data->num > 0)
return data->arr[data->num-1];
return nullptr;
#endif
}
/**
* @js NA
*/
CC_DEPRECATED_ATTRIBUTE Object* lastObject() { return getLastObject(); }
/** Returns 一个随机的 element
* @js NA
* @lua NA
*/
Object* getRandomObject();
/**
* @js NA
*/
CC_DEPRECATED_ATTRIBUTE Object* randomObject() { return getRandomObject(); }
/** Returns object 是否存在于 array 的标记.
* @js NA
*/
bool containsObject(Object* object) const;
/** @since 1.1
* @js NA
*/
bool isEqualToArray(Array* otherArray);
// Adding Objects
/** Add 一个确定的 object
* @js NA
*/
void addObject(Object* object);
/**
* @js NA
*/
/** Add 添加一个已经存在 array 里面的所有的元素
* @js NA
*/
void addObjectsFromArray(Array* otherArray);
/** Insert a certain object at a certain index
* @js NA
*/
void insertObject(Object* object, int index);
/** sets 添加一个已经存在 object 到指定索引
* @js NA
* @lua NA
*/
void setObject(Object* object, int index);
/** sets 一个已经存在 object 到指定索引， without retaining（不保存） . 所以请谨慎使用
* @js NA
* @lua NA
*/
void fastSetObject(Object* object, int index)
{
#if CC_USE_ARRAY_VECTOR
setObject(object, index);
#else
// no retain
data->arr[index] = object;
#endif
}
/**
* @js NA
* @lua NA
*/
void swap( int indexOne, int indexTwo )
{
CCASSERT(indexOne >=0 && indexOne < count() && indexTwo >= 0 && indexTwo < count(), "Invalid indices");
#if CC_USE_ARRAY_VECTOR
std::swap(data[indexOne], data[indexTwo]);
#else
std::swap(data->arr[indexOne], data->arr[indexTwo]);
#endif
}
// Removing Objects
/** Remove 最后一个 object
* @js NA
*/
void removeLastObject(bool releaseObj = true);
/** Remove 一个已经存在 object
* @js NA
*/
void removeObject(Object* object, bool releaseObj = true);
/** Remove 一个 certain 索引对应的对象
* @js NA
*/
void removeObjectAtIndex(int index, bool releaseObj = true);
/** Remove all elements
* @js NA
*/
void removeObjectsInArray(Array* otherArray);
/** Remove all objects
* @js NA
*/
void removeAllObjects();
/** 快速移除 一个已经存在的对象
* @js NA
*/
void fastRemoveObject(Object* object);
/** 快速移除 一个 certain 索引所对应的对象
* @js NA
*/
void fastRemoveObjectAtIndex(int index);
// Rearranging Content 重新排序内容
/** 交换两个元素
* @js NA
*/
void exchangeObject(Object* object1, Object* object2);
/** 交换 3 个 certain 索引所对应的对象
* @js NA
*/
void exchangeObjectAtIndex(int index1, int index2);
/** 替换指定索引对应的对象
* @js NA
*/
void replaceObjectAtIndex(int index, Object* object, bool releaseObject = true);
/** Revers（反向） the array
* @js NA
*/
void reverseObjects();
/* 收缩 array 这样的内存占用量，对应的 items 数
* @js NA
*/
void reduceMemoryFootprint();
/* override functions
* @js NA
*/
virtual void acceptVisitor(DataVisitor &visitor);
/**
* @js NA
* @lua NA
*/
virtual Array* clone() const;
// ------------------------------------------
// Iterators
// ------------------------------------------
#if CC_USE_ARRAY_VECTOR
typedef std::vector<RCPtr<Object>>::iterator iterator;
typedef std::vector<RCPtr<Object>>::const_iterator const_iterator;
/**
* @js NA
* @lua NA
*/
iterator begin() { return data.begin(); }
/**
* @js NA
* @lua NA
*/
iterator end() { return data.end(); }
const_iterator cbegin() { return data.cbegin(); }
/**
* @js NA
* @lua NA
*/
const_iterator cend() { return data.cend(); }
std::vector<RCPtr<Object>> data;
#else
/**
* @js NA
* @lua NA
*/
Object** begin() { return &data->arr[0]; }
/**
* @js NA
* @lua NA
*/
Object** end() { return &data->arr[data->num]; }
ccArray* data;
#endif
//protected:
/**
* @js NA
* @lua NA
*/
Array();
};
// end of data_structure group
/// @}
NS_CC_END
#endif // __CCARRAY_H__