Developers Manual > Cocos2d-x > Modules > Data Structures > Value

cocos2d::Value

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

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


1
class CC_DLL Value;

cocos2d::Value is a wrapper class for many primitives(int,float,double,bool,unsigned char,char* and std::string) plus std::vector<Value>, std::unordered_map<std::string,Value> and std::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 is now deprecated.

Note:When you deal with primitives and container, please use cocos2d::Vector<T>,cocos2d::Map<K,V> and cocos2d::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 of cocos2d::Value.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
union
{
    unsigned char byteVal;
    int intVal;
    float floatVal;
    double doubleVal;
    bool boolVal;

    std::string strVal;
    ValueVector* vectorVal;
    ValueMap* mapVal;
    ValueMapIntKey* intKeyMapVal;
}_field;

Type _type;

From the code snippets, base data type, strVal and _type are handled automatically by the compiler and their own destructors. The destructor of cocos2d::Value is responsible for deallocating all the resources of pointer member variables(_vectorVal,_mapVal and _intKeyMapVal).

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
Value val;   // call the default constructor
if (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 value
log("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 string
log("The description of the string value:%s",val2.getDescription().c_str());
//----------------------------------------------------
auto sp0 = Sprite::create();
Vector<Ref*>* vecV = new Vector<Ref*>();
vecV->pushBack(sp0);
Value val3(vecV);   // initialize with Vector
log("The description of the Vector value:%s",val3.getDescription().c_str());
delete vecV;
//----------------------------------------------------
Map<std::string, Ref*>* mapV = new Map<std::string, Ref*>();
mapV->insert(strV,sp0);
Value val4(mapV);   // initialize with Map
log("The description of the Map value:%s",val4.getDescription().c_str());
delete mapV;
//----------------------------------------------------
Value val6(&val4);   // initialize with Map
log("The description of the Value-type value:%s",val6.getDescription().c_str());
//----------------------------------------------------
val2 = val1;   // assigning between 2 Value-type
log("operator-> The description of val2:%s",val2.getDescription().c_str());
val2 = 4;   //assigning directly
log("operator-> The description of val4:%s",val2.getDescription().c_str());

output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
cocos2d: val is null
cocos2d: The description of the integer value:
65

cocos2d: val1.asByte() = A
cocos2d: The description of the string value:
string

cocos2d: The description of the Vector value:
true

cocos2d: The description of the Map value:
true

cocos2d: The description of the Value-type value:
true

cocos2d: operator-> The description of val2:
65

cocos2d: operator-> The description of val4:
4

Best Practice

  • Prefer cocos2d::Value and new template container(cocos2d::Vector<T> and cocos2d::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> and cocos2d::Map<K,V>.

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