Introduction to containers in Cocos2d-x3.0 (cocos2d: Vector)

V3.0 is added to the "CCVector. h" header file defined in "COCOS2DX_ROOTcocosbase. TemplateclassCC_DLLVector; cocos2d: Vector is a encapsulated container for dynamically increasing sequential access. Cocos2d: the elements in the Vector are sequentially accessed. Its low-level implementation data structure is the standard order of the standard template library.

V3.0 is added to the "CCVector. h" header file defined in "COCOS2DX_ROOT/cocos/base. Templateclass CC_DLL Vector; cocos2d: Vector is a encapsulated container for dynamically increasing sequential access. Cocos2d: the elements in the Vector are sequentially accessed. Its low-level implementation data structure is the standard order of the standard template library.

• Add v3.0

It is defined in the "CCVector. h" header file of "COCOS2DX_ROOT/cocos/base.

Templateclass CC_DLL Vector;

Cocos2d: Vector is a encapsulated container capable of dynamically increasing sequential access.

Cocos2d: Elements in the Vector are sequentially accessed. Its low-level implementation data structure is the standard sequence container std: vector in the standard template library.

Before cocos2d-x v3.0 beta, another sequential access container cocos2d: CCArray was used, but it would be discarded.

Designers designed cocos2d: Vector as a substitute for cocos2d: CCArray. Therefore, we recommend that you prioritize cocos2d: Vector.

Cocos2d: the time complexity of some Vector operations is as follows:

• Random Access, O (1)
• Insert an element to the end or delete the element from the end. O (1)
• Random insertion or deletion, O (n)

Template parameters

T-element type

• The T type must be a pointer inherited from the cocos2d: Ref type. Because the cocos2d-x's memory management model has been integrated into cocos2d: Vector, type parameters cannot be other types including basic types.

Memory Management

Cocos2d: The Vector class only contains one member data:

std::vector
 
   _data;
 

_ Data memory management is automatically handled by the compiler. If a cocos2d: Vector type is declared, you do not have to bother releasing the memory.

Note: using modern c ++, local storage objects are better than Heap Storage objects. Therefore, do not apply for cocos2d: Vector heap objects using the new operation. Use stack objects.

If you really want to dynamically allocate the heap cocos2d: Vector, overwrite the original pointer with a smart pointer.

Warning cocos2d: Vector is not a subclass of cocos2d: Ref, so do not use retain/release and reference count memory management like other cocos2d classes.

Basic usage

The authors used the basic std: vector Operation and the memory management rules of the cocos2d-x to overwrite the previous normal operation of the template.

Therefore, the pushBack () operation will retain the passed parameters, while popBack () will release the last element in the container.

When using these operations, you need to pay special attention to these managed objects. This is often a trap for new users.

Warning cocos2d: The Vector does not overload the [] operation. Therefore, you cannot directly use the subscript [I] to obtain the I-bit element.

Cocos2d: Vector provides different types of iterators, so we can benefit from the c ++ standard function library. We can use a large number of standard generic algorithms and for_each loops.

In addition to std: vector container operations, developers also add many standard algorithms such as std: find, std: reverse, and std: swap, these algorithms simplify many common operations.

To learn more about api use cases, refer to the source code of cocos2d-x 3.0 and the examples included in the compressed package.

Below are some simple examples:

//create Vector
 
   with default size and add a sprite into itauto sp0 =Sprite::create();sp0->setTag(0);//here we use shared_ptr just as a demo. in your code, please use stack object insteadstd::shared_ptr
  
   >  vec0 = std::make_shared
   
    >();//default constructorvec0->pushBack(sp0);//create a Vector
    
      with a capacity of 5 and add a sprite into itauto sp1 =Sprite::create();sp1->setTag(1);//initialize a vector with a capacityVector
     
        vec1(5);//insert a certain object at a certain indexvec1.insert(0, sp1);//we can also add a whole vectorvec1.pushBack(*vec0);for(auto sp : vec1){    log("sprite tag = %d", sp->getTag());}Vector
      
        vec2(*vec0);if(vec0->equals(vec2)){//returns true if the two vectors are equal log("pVec0 is equal to pVec2");}if(!vec1.empty()){//whether the Vector is empty//get the capacity and size of the Vector, noted that the capacity is not necessarily equal to the vector size.if(vec1.capacity()== vec1.size()){ log("pVec1->capacity()==pVec1->size()");}else{ vec1.shrinkToFit();//shrinks the vector so the memory footprint corresponds with the number of items log("pVec1->capacity()==%zd; pVec1->size()==%zd",vec1.capacity(),vec1.size());}//pVec1->swap(0, 1); //swap two elements in Vector by their index vec1.swap(vec1.front(), vec1.back());//swap two elements in Vector by their valueif(vec2.contains(sp0)){//returns a Boolean value that indicates whether object is present in vector log("The index of sp0 in pVec2 is %zd",vec2.getIndex(sp0));}//remove the element from the Vector vec1.erase(vec1.find(sp0));//pVec1->erase(1);//pVec1->eraseObject(sp0,true);//pVec1->popBack();
       
vec1.clear();//remove all elementslog("The size of pVec1 is %zd",vec1.size());}
      
     
    
   
  
 

Output:

Cocos2d: sprite tag =1Cocos2d: sprite tag =0Cocos2d: pVec0 is equal to pVec2Cocos2d: pVec1->capacity()==2; pVec1->size()==2Cocos2d:The index of sp0 in pVec2 is0Cocos2d:The size of pVec1 is0

Recommended Practices

• Stack-based cocos2d: Vector is used preferentially for heap-based
• When cocos2d: Vector is passed as a parameter, it is declared as a constant reference: const cocos2d: Vector &
• If the returned value is cocos2d: Vector, the compiler will optimize it to a moving operation.
• Do not use any data type that does not inherit cocos2d: Ref as cocos2d: Vector.