cocos2d::Value

• Since: v3.0 beta
• Language: C++

Defined in the head "CCValue.h" loated in "COCOS2DX_ROOT/cocos/base"

---

1
class Value;

---

cocos2d::Value is a wrapper class for many primitives(int,float,double,bool,unsigned char,char* andstd::string) plus std::vector<Value>, std::unordered_map<std::string,Value> andstd::unordered_map<int,Value>.

You can put all the primitives mentioned above into a cocos2d::Value object and convert it to the corresponding primitive. The opposite is vice verse.

Internally, cocos2d::Value uses a union variable to hold all kinds of primitives which saves a lot of memory space.

Before cocos2d-x v3.0 beta, there are CCBool, CCFloat,CCDouble, CCinteger primitive wrapper. These classes will be deprecated in the future.

Note:When you deal with primitives and container, please use cocos2d::Vector<T>,cocos2d::Map<K,V> andcocos2d::Value.

Memory Management

The memory of cocos2d::Value is handled automatically by it's own destructor. So please stick to the best practice of c++ memory management rules when handling the memory ofcocos2d::Value.

The cocos2d::Value class contains the following data members:

123456789101112131415
union{    unsigned char byteVal;    int intVal;    float floatVal;    double doubleVal;    bool boolVal;}_baseData;std::string _strData;ValueVector* _vectorData;ValueMap* _mapData;ValueMapIntKey* _intKeyMapData;Type _type;

From the code snippets, _baseData, _strData and _type data members' memory are handled automatically by the compiler and their own destructors. The destructor ofcocos2d::Value is responsible for deallocating all the resources of pointer member variables(_vectorData,_mapData and_intKeyMapData).

WARNING: cocos2d::Value doesn't use retain/release and refcount memory management like other cocos2d classes!

Basic Usage

The usage of cocos2d::Value is very straightforward.

Here is a simple usage example:

1234567891011121314151617181920212223242526272829303132333435363738
Value val;   // call the default constructorif (val.isNull()) {    log("val is null");}else{    std::string str =val.getDescription();    log("The description of val0:%s",str.c_str());}//----------------------------------------------------Value val1(65);   // initialize with a integer//Value val1(3.4f);   // initialize with a float value//Value val1(3.5);   // initialize with a double valuelog("The description of the integer value:%s",val1.getDescription().c_str());log("val1.asByte() = %c",val1.asByte());//----------------------------------------------------std::string strV = "string";Value val2(strV);   // initialize with stringlog("The description of the string value:%s",val2.getDescription().c_str());//----------------------------------------------------auto sp0 = Sprite::create();Vector<Object*>* vecV = new Vector<Object*>();vecV->pushBack(sp0);Value val3(vecV);   // initialize with Vectorlog("The description of the Vector value:%s",val3.getDescription().c_str());delete vecV;//----------------------------------------------------Map<std::string, Object*>* mapV = new Map<std::string, Object*>();mapV->insert(strV,sp0);Value val4(mapV);   // initialize with Maplog("The description of the Map value:%s",val4.getDescription().c_str());delete mapV;//----------------------------------------------------Value val6(&val4);   // initialize with Maplog("The description of the Value-type value:%s",val6.getDescription().c_str());//----------------------------------------------------val2 = val1;   // assigning between 2 Value-typelog("operator-> The description of val2:%s",val2.getDescription().c_str());val2 = 4;   //assigning directlylog("operator-> The description of val4:%s",val2.getDescription().c_str());

output:

12345678910111213141516171819202122
cocos2d: val is nullcocos2d: The description of the integer value:65cocos2d: val1.asByte() = Acocos2d: The description of the string value:stringcocos2d: The description of the Vector value:truecocos2d: The description of the Map value:truecocos2d: The description of the Value-type value:truecocos2d: operator-> The description of val2:65cocos2d: operator-> The description of val4:4

Best Practice

• Prefer cocos2d::Value and new template container(cocos2d::Vector<T> andcocos2d::Map<K,V>) over cocos2d::CCBool, cocos2d::CCFloat,cocos2d::CCDouble,cocos2d::CCString,cocos2d::CCInteger and old Objective-c style container(cocos2d::CCArray and cocos2d::CCDictionary).
• When you want to deal with primitives aggregate, wrap the primitives with cocos2d::Value and combine them with the new template container cocos2d::Vector<T> andcocos2d::Map<K,V>.