cocos2d-x 之 CCArray 源码分析

class CC_DLL CCArray : public CCObject
{
public:
    /************************************************************************/
    /* 构造析构函数                                                         */
    /************************************************************************/
    //构造函数
    CCArray();

    //capacity 为数组元素的个数，创建的数组至少有1个元素，如果传的是0，也会创建包含一个元素大小的数组
    CCArray(unsigned int capacity);

    //构造函数
    ~CCArray();



    /************************************************************************/
    /* 创建数组 ，一共有7个函数                                             */
    /************************************************************************/
    // 创建一个新的数组，默认大小为1个元素的数组
    static CCArray* create();

    //根据数组中包含的的元素创建一个新的数组，注意，最后一个参数必须为NULL。如CCArray::create(pobj1,pobj2,NULL);
    static CCArray* create(CCObject* pObject, ...);

    //创建一个包含一个元素pObject的数组
    static CCArray* createWithObject(CCObject* pObject);
   
    //创建一个包含capacity个元素的数组
    static CCArray* createWithCapacity(unsigned int capacity);
    
    //根据一个已经存在的数组创建一个新的数组，这个函数没有实现。暂时用不到
    static CCArray* createWithArray(CCArray* otherArray);

    /*
        根据一个 .plist 文件创建一个新的数组，创建的数组调用了autorelease()函数，所以不用担心内存的释放
    */
    static CCArray* createWithContentsOfFile(const char* pFileName);
    
    /*
        与上面一个函数功能一样，但是没有调用autorelease()函数，所以使用完后需要调用 release();
    */
    static CCArray* createWithContentsOfFileThreadSafe(const char* pFileName);



    /************************************************************************/
    /* 初始化数组 ，一共有5个函数                                           */
    /************************************************************************/
    //初始化一个数组，此数组只包含一个元素大小
    bool init();
    
    //初始化一个数组，此数组只包含一个元素，这个元素是pObject
    bool initWithObject(CCObject* pObject);
    
    //初始化一个数组，此数组包含多个指定的元素，注：函数有最后一个参数为NULL
    bool initWithObjects(CCObject* pObject, ...);
 
    //初始化一个数组，此数组包含capacity个元素大小，如果capacity为0，那么创建的是一个只有1个元素大小的数组
    bool initWithCapacity(unsigned int capacity);

    //初始化一个数组，数组的元素的大小等于otherArray中已经存在的元素的个数相同，并且把other中的元素分别赋值给新创建的数组
    //注：在把otherArray中的元素复制到新创建的数组中的过程中，别忘了 pObject->retain()
    bool initWithArray(CCArray* otherArray);

    
    /************************************************************************/
    /* 初始化数组 ，一共有8个函数                                           */
    /************************************************************************/
    //返回数组中已经存在的元素的个数
    unsigned int count() const;

    //返回数组的总大小
    unsigned int capacity() const;

    //根据一个给定的元素，返回此元素在数组中的索引，以第1次找到的为准，如果数组中不包含这个元素，返回CC_INVALID_INDEX
    unsigned int indexOfObject(CCObject* object) const;
    
    //根据一个给定的数组中的索引，返回其对象
    CCObject* objectAtIndex(unsigned int index);
   
    //返回数组中的最后一个元素
    CCObject* lastObject();

    //随机返回数组中的一个元素
    CCObject* randomObject();

    //判断元素object是否包含在数组中，true 则元素在此数组中，false则表示元素不在数组中
    bool containsObject(CCObject* object) const;
    
    //判断两个数组是否相等，具体是指两个数组中的相应的索引上的元素一一相等，则两数组相等
    bool isEqualToArray(CCArray* pOtherArray);

    /************************************************************************/
    /* 添加元素 ，一共有3个函数                                             */
    /************************************************************************/
    //在数组的最后一个元素的后面再添加一个元素object，如果数组空间不足，则数组会再动态申请2倍于以前数组的最大的空间
    void addObject(CCObject* object);

    //把数组otherArray中的相应元素分别添加到数组中，如果空间不足，则数组会再动态申请2倍于以前数组的最大的空间
    void addObjectsFromArray(CCArray* otherArray);
    
    //将object插入到数组中index位置上，从index位置往后每个元素向后移动一个位置
    //这个过程使用了memmove()函数
    void insertObject(CCObject* object, unsigned int index);

    /************************************************************************/
    /* 删除元素 ，一共有7个函数                                             */
    /************************************************************************/
    //删除数组中的最后一个元素，如果bReleaseObj为true，则会调用元素的release()函数
    //注：特别注意，这个函数实际上并没有真正的把元素删除，只是把当前的元素的个数减1,从而可以正确确定索引的范围了
    void removeLastObject(bool bReleaseObj = true);

    //删除数组中第一次出现的object ， bReleaseObj的意义同上
    void removeObject(CCObject* object, bool bReleaseObj = true);
   
    //删除指定索引上的元素
    void removeObjectAtIndex(unsigned int index, bool bReleaseObj = true);
    
    //删除数组中所有包含otherArray中元素的元素
    void removeObjectsInArray(CCArray* otherArray);

    //删除数组中所有的元素，但数组的内存没有释放 
    void removeAllObjects();
  
    //fast删除，最快速的删除，原理其实就是把数组中的最后一个元素赋值给了object对应的位置。并且数组的当前元素个数减1
    //使用此函数一定要注意，要删除的那个位置的值不存在了
    //只是替换了数组的最后一个元素，很可能会造成内存泄露，因为并没有真正删除object
    void fastRemoveObject(CCObject* object);
    
    //原理同上
    void fastRemoveObjectAtIndex(unsigned int index);

    // Rearranging Content

    //交换数组中两个元素，就是object1跑到object2的位置上了，同理，object2跑到object1的位置上了
    void exchangeObject(CCObject* object1, CCObject* object2);
   
    //交换数组中index1和index2两个索引对应的两个元素，其实上面的函数就是调用了此函数
    void exchangeObjectAtIndex(unsigned int index1, unsigned int index2);

    //将uIndex位置的元素替换为pObject
    void replaceObjectAtIndex(unsigned int uIndex, CCObject* pObject, bool bReleaseObject = true);

    //翻转数组
    void reverseObjects();

    //缩小数组的空间，让数组占用的内存符合元素的数量
    void reduceMemoryFootprint();
  

    //virtual函数，返回当前数组的一个副本
    virtual CCObject* copyWithZone(CCZone* pZone);

    /* override functions */
    virtual void acceptVisitor(CCDataVisitor &visitor);

public:
    ccArray* data;
};