CCDictionary(封装了哈希表.可以加入两种元素:键为整型或字符串值为ccobject.CCDICT_FOREACH objectForKey allKeysForObject setObj)

#ifndef __CCDICTIONARY_H__
#define __CCDICTIONARY_H__

#include "support/data_support/uthash.h"
#include "CCObject.h"
#include "CCArray.h"
#include "CCString.h"

NS_CC_BEGIN

class CCDictionary;

/**
* CCDictElement is used for traversing（遍历） CCDictionary.
*
* A CCDictElement is one element of CCDictionary, it contains two properties, key and object. //字典元素是字典一个元素 它包含2个属性
键 和 值
* Its key has two different type (integer and string). //键有两个不同类型 整型和字符串
*
* @note The key type is unique（唯一的）, all the elements in CCDictionary has the same key type(integer or string).

* CCDictElement* pElement;
* CCDICT_FOREACH(dict, pElement)
* {
* const char*key = pElement->getStrKey();
* // You certainly know the type of value, so we assume that it's a CCSprite.
* CCSprite* pSprite = (CCSprite*)pElement->getObject();
* // ......
* }
*
*/
class CC_DLL CCDictElement //字典元素
{
private:
//字典元素构造函数 两种方式 1、键值为字符串 2、键值为整型 两种方式键对应的值都是CCObject。
CCDictionary is its friend class.
CCDictElement(const char* pszKey, CCObject* pObject);

CCDictElement(intptr_t iKey, CCObject* pObject);

public:
~CCDictElement();

// Inline functions need to be implemented(实行) in header file on Android.

inline const char* getStrKey() const
//像这种简单的函数 设置为内联函数。 编译时直接文本替换（类似宏 因为函数简单可以这样处理） 节省了调用函数时的时间开销
{
CCAssert(m_szKey[0] != '\0', "Should not call this function for integer dictionary");
return m_szKey;
}

inline intptr_t getIntKey() const
{
CCAssert(m_szKey[0] == '\0', "Should not call this function for string dictionary");
return m_iKey;
}

inline CCObject*
getObject() const { return m_pObject; }

private:
#define MAX_KEY_LEN 256 //定义字符串key最大长度 不一定非要在文件开头定义
// char array is needed for HASH_ADD_STR in UT_HASH.

// So it's a pain that all elements will allocate 256 bytes for this array.
char m_szKey[MAX_KEY_LEN]; // hash key of string type
intptr_t m_iKey; // hash key of integer type
CCObject* m_pObject; // hash value
public:
UT_hash_handle hh; // makes this class hash able 句柄

////////////
int类型key

　　总结int类型key使用方法，可以看到其查找和插入分别使用专用接口:HASH_FIND_INT和ASH_ADD_INT。

　　4.2. 字符指针char*类型key与字符数组char key[100]类型key

　　特别注意在Strting类型中，uthash对指针char*和字符数组(例如char key[100])做了区分，这两种情况下使用的接口函数时不一样的。在添加的时候，key的类型为指针时使用接口函数HASH_ADD_KEYPTR，key的类型为字符数组时，使用接口函数HASH_ADD_STR，除了添加的接口不一样外，其他的查找、删除、变量等接口函数都是一样的。
/////////

friend class CCDictionary; // declare（声明） CCDictionary as friend class
};

/** The macro for traversing（遍历） dictionary
*
* @note It's faster than getting all keys and traversing keys to get objects by objectForKey.
* It's also safe to remove elements while traversing.
*/
#define CCDICT_FOREACH(__dict__, __el__) \
//遍历字典 允许遍历时删除元素
CCDictElement* pTmp##__dict__##__el__ = NULL; \
if (__dict__) \
HASH_ITER(hh, (__dict__)->m_pElements, __el__, pTmp##__dict__##__el__)

/**
* Only the pointer of CCObject or its subclass can be inserted to CCDictionary.//仅object或其子类的 指针允许插入字典作为值
* // Create a dictionary, return an autorelease object.
* CCDictionary* pDict = CCDictionary::create();
*
* // Insert objects to dictionary
* CCString* pValue1 = CCString::create("100");
* CCString* pValue2 = CCString::create("120");
* CCInteger* pValue3 = CCInteger::create(200);
* pDict->setObject(pValue1, "key1");
* pDict->setObject(pValue2, "key2");
* pDict->setObject(pValue3, "key3");
*
* // Get the object for key
* CCString* pStr1 = (CCString*)pDict->objectForKey("key1");
* CCLog("{ key1: %s }", pStr1->getCString());
* CCInteger* pInteger = (CCInteger*)pDict->objectForKey("key3");
* CCLog("{ key3: %d }", pInteger->getValue());
* @endcode
*
*/

class CC_DLL CCDictionary : public CCObject //内部通过哈希表实现
{
public:
CCDictionary();

~CCDictionary();

unsigned int
count();

{
return HASH_COUNT(m_pElements);
}
/**
* Return all keys of elements.
*/
CCArray*
allKeys();// 返回所有字典元素的 键数组

/**
* Get all keys according to the specified object.
* @warning We use '==' to compare two objects
*/
CCArray*
allKeysForObject(CCObject* object);//得到所有对应参数值的 键数组

CCObject*
objectForKey(const std::string& key); //通过键 得到值

CCObject*
objectForKey(intptr_t key);

/** Get the value according to the specified string key.
*
* @note Be careful to use this function since it assumes（假设） the objects in the dictionary are CCString pointer.
* @param key The string key for searching
* @return An instance of CCString.
* It will return an empty string if the objects aren't CCString pointer or the key wasn't found.
* @see valueForKey(intptr_t)
*/
const CCString* valueForKey(const std::string& key);//
CCObject 是CCString时可以用这个

const CCString* valueForKey(intptr_t key);

void
setObject(CCObject* pObject, const std::string& key); //插入元素

void
setObject(CCObject* pObject, intptr_t key);//插入元素

void
removeObjectForKey(const std::string& key); //删除对应给定键的ccobjet

void
removeObjectForKey(intptr_t key);//删除对应给定键的ccobjet

void
removeObjectsForKeys(CCArray* pKeyArray);
//删除对应给定键数组的所有ccobjets

void
removeObjectForElememt(CCDictElement* pElement);
//直接删除一个给定元素

void
removeAllObjects();

/// @{
/// @name Function override
/**
* This function is used for deepcopy elements from source dictionary to destination dictionary.
* You shouldn't invoke this function manually since it's called by CCObject::copy.
*/
virtual CCObject* copyWithZone(CCZone* pZone);
/// @}

CCObject*
randomObject(); //随机得到字典里一个元素

static CCDictionary*
create();
//创建字典 空得

static CCDictionary*
createWithDictionary(CCDictionary* srcDict); //使用已有字典 创建字典

static CCDictionary*
createWithContentsOfFile(const char *pFileName);
//使用plist文件创建一个字典

/**
* Write a dictionary to a plist file.
* @param fullPath The full path of the plist file. You can get writeable path by getWritablePath()
*/
bool
writeToFile(const char *fullPath);
//把字典数据写入一个plist文件

/**
* Create a dictionary with a plist file.
*
* @note the return object
isn't an autorelease object.
* This can make sure not using autorelease pool in a new thread.
* Therefore, you need to manage the lifecycle of the return object.
* It means that when you don't need it, CC_SAFE_RELEASE needs to be invoked.
*
* @param pFileName The name of the plist file.
* @return A dictionary which isn't an autorelease object.
*/
static CCDictionary*
createWithContentsOfFileThreadSafe(const char *pFileName);
///,,,,,,,,,,,,,,

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

private:
/**
* For internal usage, invoked by setObject.
*/
//内部函数 被setObject调用
void setObjectUnSafe(CCObject* pObject, const std::string& key);
void setObjectUnSafe(CCObject* pObject, const intptr_t key);

public:
/**
* All the elements in dictionary.
*
* @note For internal usage, we need to declare this member variable as public since it's used in UT_HASH.
*/
CCDictElement* m_pElements; //是公有的!!!!!!
private:

/** The support type of dictionary, it's confirmed when setObject is invoked. */
enum
CCDictType
{
kCCDictUnknown = 0,
kCCDictStr,
kCCDictInt
};

/**
* The type of dictionary, it's assigned to kCCDictUnknown by default.
*/
CCDictType m_eDictType;
};

NS_CC_END

#endif /* __CCDICTIONARY_H__ */