CCDictionary详解

<a target=_blank href="http://www.cnblogs.com/newlist/p/3238168.html">原文链接</a>

#ifndef __CCDICTIONARY_H__
#define __CCDICTIONARY_H__
//需要哈希表的支持
#include "support/data_support/uthash.h"
#include "CCObject.h"
#include "CCArray.h"
#include "CCString.h"
//Cocos2d命名空间
NS_CC_BEGIN
//声明一下CCDictionary类，因为CCDictElement要用到CCDictionary指针。
class CCDictionary;

//词典元素，或者简单理解就是词典中的一个词汇。我们从小查词典都知道，通过词汇名称或索引查找到对应的解释。解释与词汇名称或索引之间是一一对应的关系。与这种关系相同，在这个词汇类中存储一个字符串名称或一个索引以及与其相应的CCObject指针，这个CCObject指针就相当于是我们查出来的解释一样与字符串名称或索引构成了对应关系。

class CC_DLL CCDictElement
{
//定义字符串名称的长度.
    #define MAX_KEY_LEN  256
public:
//构造函数。
//参1:字符串名称。
//参2:对应的CCObject指针。
    CCDictElement(const char* pszKey, CCObject* pObject)
{
        //初始化。
        init();
        m_pObject = pObject;
        //
        const char* pStart = pszKey;
        //字符串的字节长度
        int len = strlen(pszKey);
        if (len > MAX_KEY_LEN )
        {  //如果长度大于MAX_KEY_LEN，截取后面MAX_KEY_LEN长度字符串。
            char* pEnd = (char*)&pszKey[len-1];
            pStart = pEnd - (MAX_KEY_LEN-1);
        }
        //字符串COPY
        strcpy(m_szKey, pStart);
    }
    //构造函数
    //参1:所在哈希表中的索引
    //参2:对应的CCObject指针。
    CCDictElement(int iKey, CCObject* pObject)
    {
        init();
        m_iKey = iKey;
        m_pObject = pObject;
    }
//取得名称字符串。
    inline const char* getStrKey() const
    {
        CCAssert(m_szKey[0] != '\0', "Should not call this function for integer dictionary");
        return m_szKey;
    }
//取得哈希索引。
    inline int getIntKey() const 
    {
        CCAssert(m_szKey[0] == '\0', "Should not call this function for string dictionary");
        return m_iKey;
    }
//取得CCObject指针。
    inline CCObject* getObject() const
    {
        return m_pObject;
    }

private:
    //初始化。
    inline void init()
    {
        m_iKey = 0;
        m_pObject = NULL;
        memset(m_szKey, 0, sizeof(m_szKey));
        memset(&hh, 0, sizeof(hh));
    }

private:
    char m_szKey[MAX_KEY_LEN+1]; //存储名称的字符数组。
    int  m_iKey;                 //哈希表索引
    CCObject* m_pObject;         //哈希值（CCObject指针）
public:
    UT_hash_handle hh;             //哈希表结构指针
    friend class CCDictionary;  //词典为友元类
};

//遍历词典中的所有词汇的一个宏，它内部调用HASH_ITER来进行for循环遍历链表。
#define CCDICT_FOREACH(__dict__, __el__) \
    CCDictElement* pTmp##__dict__##__el__ = NULL; \
    HASH_ITER(hh, (__dict__)->m_pElements, __el__, pTmp##__dict__##__el__)

//词典类，由CCObject派生
class CC_DLL CCDictionary : public CCObject
{
public:
    //构造函数
    CCDictionary();
    //析构函数
    ~CCDictionary();

    //取得所有词汇的数量。
    unsigned int count();

    //返回所有的查询关键字。
    CCArray* allKeys();

    //取得对应CCObject指针的所有关键字或索引值。
    CCArray* allKeysForObject(CCObject* object);
    //通过查询关键字取得对应CCObject指针
    CCObject* objectForKey(const std::string& key);
    //通过哈希索引值取得对应CCObject指针
    CCObject* objectForKey(int key);
    //通过查询关键字取得对应CCString指针
    const CCString* valueForKey(const std::string& key);
    //通过哈希索引值取得对应CCString指针
    const CCString* valueForKey(int key);
    //设置一个CCObject和对应的名称存入词典。
    void setObject(CCObject* pObject, const std::string& key);
    //设置一个CCObject和对应的哈希索引存入词典。
    void setObject(CCObject* pObject, int key);
    //按照查询关键字找到对应CCObject并删除。
    void removeObjectForKey(const std::string& key);
    //按照哈希索引找到对应CCObject并删除。
    void removeObjectForKey(int key);
    //按照容器中的查询关键字找到对应CCObject并删除。
    void removeObjectsForKeys(CCArray* pKeyArray);
    //从词典中删除相应的词汇。
    void removeObjectForElememt(CCDictElement* pElement);
    //从词典中清空所有的词汇。
    void removeAllObjects();
    //重载CCObject的拷贝函数。产生一个一模一样的词典。
    virtual CCObject* copyWithZone(CCZone* pZone);

    //静态函数，取得单例的词典。请改用create函数，因为这个函数以后将被删除掉。
    CC_DEPRECATED_ATTRIBUTE static CCDictionary* dictionary();

//静态函数，取得一个指定词典的COPY，请改用createWithDictionary函数，因为这个函数以后将被删除掉。
    CC_DEPRECATED_ATTRIBUTE static CCDictionary* dictionaryWithDictionary(CCDictionary* srcDict);
    
//静态函数:从一个plist文件中加载词典内容。此函数创建的词典是交由内存管理器来进行资源计数的，不需手动release。但请改用createWithContentsOfFile函数，因为这个函数以后也将被删除掉。
    CC_DEPRECATED_ATTRIBUTE static CCDictionary* dictionaryWithContentsOfFile(const char *pFileName);

    //静态函数：从一个plist文件中加载词典内容，但此函数是多线程安全的，另外此函数创建的词典需要手动release。请改用 createWithContentsOfFileThreadSafe函数，因为这个函数以后也将被删除掉。
    CC_DEPRECATED_ATTRIBUTE static CCDictionary* dictionaryWithContentsOfFileThreadSafe(const char *pFileName);
    //静态函数，创建一个新词典
    static CCDictionary* create();
    //静态函数，取得一个指定词典的COPY。
    static CCDictionary* createWithDictionary(CCDictionary* srcDict);

    //静态函数:从一个plist文件中加载词典内容。
    static CCDictionary* createWithContentsOfFile(const char *pFileName);
    //静态函数：从一个plist文件中加载词典内容，但此函数是多线程安全的，另外此函数创建的词典需要手动release。
    static CCDictionary* createWithContentsOfFileThreadSafe(const char *pFileName);

private:
    //将CCObject实例指针与对应的字符串名称存入哈希表。
    void setObjectUnSafe(CCObject* pObject, const std::string& key);
    //将CCObject实例指针与对应的索引值存入哈希表。
    void setObjectUnSafe(CCObject* pObject, const int key);
    
public:
    //词汇的哈希表头部结构指针。
    CCDictElement* m_pElements;
private:
    //词典查询类型。
    enum CCDictType
    {
        kCCDictUnknown = 0,
        kCCDictStr,//字符串名称
        kCCDictInt //索引
    };
    CCDictType m_eDictType;        //当前词典查询类型。一个词典实例要求只有一种固定词典查询类型。
    CCDictType m_eOldDictType;  //上次词典查询类型。这个变量是用来比对是否改变了词典查询类型。
};
NS_CC_END