Outdated Docs > CCArray

CCArray

Introduction

CCArray is a fully supported class of cocos2d. It is used for optimization in your game. You can find the CCArray class files in the cocos2d/Support group in the project. It’s used internally by cocos2d and is similar to Apple’s NSMutableArray class—except that CCArray performs better:) .

Note: CCArray and CCDictionary classes are used to hold most cocos2d-x classes but they are still not as powerful as STL library. Thus, there is no need to replace STL with CCArray or CCDictionary.

CCArray only provides an object-oriented wrapper class

CCArray is inherited from the CCObject class (CCObject’s main purpose is automatic memory management), and provided a series of interface, including:

Create

 /** Create an array */
    static CCArray* create();
    /** Create an array with some objects */
    static CCArray* create(CCObject* pObject, …);
    /** Create an array with one object */
    static CCArray* createWithObject(CCObject* pObject);
    /** Create an array with capacity */
    static CCArray* createWithCapacity(unsigned int capacity);
    /** Create an array with an existing array */
    static CCArray* createWithArray(CCArray* otherArray);

Insert

/** Add a certain object */
    void addObject(CCObject* object);
    /** Add all elements of an existing array */
    void addObjectsFromArray(CCArray* otherArray);
    /** Insert a certain object at a certain index */
    void insertObject(CCObject* object, unsigned int index);

Delete

/** Remove last object */
    void removeLastObject(bool bReleaseObj = true);
    /** Remove a certain object */
    void removeObject(CCObject* object, bool bReleaseObj = true);
    /** Remove an element with a certain index */
    void removeObjectAtIndex(unsigned int index, bool bReleaseObj = true);
    /** Remove all elements */
    void removeObjectsInArray(CCArray* otherArray);
    /** Remove all objects */
    void removeAllObjects();
    /** Fast way to remove a certain object */
    void fastRemoveObject(CCObject* object);
    /** Fast way to remove an element with a certain index */
    void fastRemoveObjectAtIndex(unsigned int index);

where there is remove and fastRemove, see the source code, remove is a relatively complete removed from the CCArray object fastRemove just will correspond in a CCArray element in a release from the code, main difference is that there are no speak delete elements after the elements to move forward over the removed element location, differential code is as follows:

unsigned int remaining = arr->num - index;
 if(remaining>0)
{
    memmove((void *)&arr->arr[index], (void *)&arr->arr[index+1], remaining * sizeof(CCObject*));
}

Looping

In Step by Step Tutorials Chapter 5 - How to Detect the Collisions , The function update() below invoke CCARRAY_FOREACH(arr,obj) is used to Loop the CCArray(*targets and*projectiles) to detect collisions every frame.

Declare it in HelloWorldScene.h and Define it in HelloWorldScene.cpp.

void HelloWorld::update(ccTime dt)
{
    CCArray *projectilesToDelete = new CCArray;
    CCObject* it = NULL;
    CCObject* jt = NULL;


 CCARRAY_FOREACH(_projectiles, it)
 {
  CCSprite *projectile = dynamic_cast(it);
  CCRect projectileRect = CCRectMake(
   projectile->getPosition().x - (projectile->getContentSize().width/2),
   projectile->getPosition().y - (projectile->getContentSize().height/2),
   projectile->getContentSize().width,
   projectile->getContentSize().height);


  CCArray* targetsToDelete =new CCArray;


        CCARRAY_FOREACH(_targets, jt)
  {
   CCSprite *target = dynamic_cast(jt);
   CCRect targetRect = CCRectMake(
    target->getPosition().x - (target->getContentSize().width/2),
    target->getPosition().y - (target->getContentSize().height/2),
    target->getContentSize().width,
    target->getContentSize().height);


   // if (CCRect::CCRectIntersectsRect(projectileRect, targetRect))
            if (projectileRect.intersectsRect(targetRect))
   {
    targetsToDelete->addObject(target);
   }
  }


        CCARRAY_FOREACH(targetsToDelete, jt)
  {
   CCSprite *target = dynamic_cast(jt);
   _targets->removeObject(target);
   this->removeChild(target, true);
    }


    if (targetsToDelete->count() >0)
    {
      projectilesToDelete->addObject(projectile);
    }
    targetsToDelete->release();
  }


    CCARRAY_FOREACH(projectilesToDelete, it)
 {
  CCSprite* projectile = dynamic_cast(it);
  _projectiles->removeObject(projectile);
  this->removeChild(projectile, true);
 }
 projectilesToDelete->release();
} 

CCArray vs. NSArray

CCArray is faster but it also means objects in CCArray will change positions, so if you rely on a specific ordering of objects, you shouldn’t use the fastRemoveObject methods.

Speed Tests

Following code that is measured for CCArray and NSArray loops(200 elements):

  • Test A (NSArray) :

<!-- -->

for(int w = 0; w<100; w++){
                for(id object in arrayNS){
                        //Do something
                }
        }
  • Test B (CCArray) :

<!-- -->

ccArray *arrayData = array->data;
id object;
int nu = arrayData->num;
for(int w = 0; w<100; w++){
                CCARRAY_FOREACH(arrayData, object){
                        object = arrayData->arr[i];
                        //Do something
                }
        }

The results

A mere 10% read access performance increase for CCArray compared to NS (Mutable)Array when using a for loop. And a tiny, negligible improvement when using the CCARRAY_FOREACH keyword compared to NS (Mutable)Array’s fast enumerator for(CCNode* node in array) to iterate over the array. Both these results are in the same ballpark with the C-Array, and I was pleasantly surprised to see the CCArray and NS (Mutable)Array all perform basically the same as the C-Array when using fast enumeration, with CCArray just a tiny fraction faster – exactly the same performance as a pure C-Array.

Use matters needing attention

CCArray generally will not be added to other classes, so its reference count is 1, and is set to autorelease. Creating the CCArray object to retain, and in its destructor method called release to release memory.

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.