Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1846 from dumganhar/iss1650-doxgen-ccdictionary 

issue #1650: Adding detailed doxgen comments for CCDictionary.
This commit is contained in:
James Chen 2013-01-15 02:49:51 -08:00
parent ed91017e58 5d7cc39edd
commit e750c6e163
2 changed files with 372 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
cocos2dx/cocoa/CCDictionary.cpp
View File

@ -1,3 +1,27 @@
/****************************************************************************
Copyright (c) 2012 - 2013 cocos2d-x.org
http://www.cocos2d-x.org
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
****************************************************************************/
#include "CCDictionary.h"
#include "CCString.h"
#include "CCInteger.h"
@ -6,10 +30,47 @@ using namespace std;
NS_CC_BEGIN
// -----------------------------------------------------------------------
// CCDictElement
CCDictElement::CCDictElement(const char* pszKey, CCObject* pObject)
{
CCAssert(pszKey && strlen(pszKey) > 0, "Invalid key value.");
m_iKey = 0;
const char* pStart = pszKey;
int len = strlen(pszKey);
if (len > MAX_KEY_LEN )
{
char* pEnd = (char*)&pszKey[len-1];
pStart = pEnd - (MAX_KEY_LEN-1);
}
strcpy(m_szKey, pStart);
m_pObject = pObject;
memset(&hh, 0, sizeof(hh));
}
CCDictElement::CCDictElement(intptr_t iKey, CCObject* pObject)
{
m_szKey[0] = '\0';
m_iKey = iKey;
m_pObject = pObject;
memset(&hh, 0, sizeof(hh));
}
CCDictElement::~CCDictElement()
{
}
// -----------------------------------------------------------------------
// CCDictionary
CCDictionary::CCDictionary()
: m_pElements(NULL)
, m_eDictType(kCCDictUnknown)
, m_eOldDictType(kCCDictUnknown)
{
}
@ -37,8 +98,8 @@ CCArray* CCDictionary::allKeys()
HASH_ITER(hh, m_pElements, pElement, tmp)
{
CCString* pOneKey = new CCString(pElement->m_szKey);
pOneKey->autorelease();
pArray->addObject(pOneKey);
CC_SAFE_RELEASE(pOneKey);
}
}
else if (m_eDictType == kCCDictInt)
@ -46,8 +107,8 @@ CCArray* CCDictionary::allKeys()
HASH_ITER(hh, m_pElements, pElement, tmp)
{
CCInteger* pOneKey = new CCInteger(pElement->m_iKey);
pOneKey->autorelease();
pArray->addObject(pOneKey);
CC_SAFE_RELEASE(pOneKey);
}
}
@ -70,7 +131,7 @@ CCArray* CCDictionary::allKeysForObject(CCObject* object)
{
CCString* pOneKey = new CCString(pElement->m_szKey);
pArray->addObject(pOneKey);
pOneKey->release();
CC_SAFE_RELEASE(pOneKey);
}
}
}
@ -82,7 +143,7 @@ CCArray* CCDictionary::allKeysForObject(CCObject* object)
{
CCInteger* pOneKey = new CCInteger(pElement->m_iKey);
pArray->addObject(pOneKey);
pOneKey->release();
CC_SAFE_RELEASE(pOneKey);
}
}
}
@ -127,7 +188,7 @@ CCObject* CCDictionary::objectForKey(int key)
const CCString* CCDictionary::valueForKey(const std::string& key)
{
CCString* pStr = (CCString*)objectForKey(key);
CCString* pStr = dynamic_cast<CCString*>(objectForKey(key));
if (pStr == NULL)
{
pStr = CCString::create("");
@ -137,7 +198,7 @@ const CCString* CCDictionary::valueForKey(const std::string& key)
const CCString* CCDictionary::valueForKey(int key)
{
CCString* pStr = (CCString*)objectForKey(key);
CCString* pStr = dynamic_cast<CCString*>(objectForKey(key));
if (pStr == NULL)
{
pStr = CCString::create("");
@ -148,12 +209,12 @@ const CCString* CCDictionary::valueForKey(int key)
void CCDictionary::setObject(CCObject* pObject, const std::string& key)
{
CCAssert(key.length() > 0 && pObject != NULL, "Invalid Argument!");
if (m_eOldDictType == kCCDictUnknown)
if (m_eDictType == kCCDictUnknown)
{
m_eOldDictType = kCCDictStr;
}
m_eDictType = kCCDictStr;
CCAssert(m_eDictType == m_eOldDictType, "this dictionary does not use string as key.");
}
CCAssert(m_eDictType == kCCDictStr, "this dictionary doesn't use string as key.");
CCDictElement *pElement = NULL;
HASH_FIND_STR(m_pElements, key.c_str(), pElement);
@ -174,12 +235,12 @@ void CCDictionary::setObject(CCObject* pObject, const std::string& key)
void CCDictionary::setObject(CCObject* pObject, int key)
{
CCAssert(pObject != NULL, "Invalid Argument!");
if (m_eOldDictType == kCCDictUnknown)
if (m_eDictType == kCCDictUnknown)
{
m_eOldDictType = kCCDictInt;
}
m_eDictType = kCCDictInt;
CCAssert(m_eDictType == m_eOldDictType, "this dictionary does not use integer as key.");
}
CCAssert(m_eDictType == kCCDictInt, "this dictionary doesn't use integer as key.");
CCDictElement *pElement = NULL;
HASH_FIND_INT(m_pElements, &key, pElement);
@ -200,11 +261,12 @@ void CCDictionary::setObject(CCObject* pObject, int key)
void CCDictionary::removeObjectForKey(const std::string& key)
{
if (m_eOldDictType == kCCDictUnknown)
if (m_eDictType == kCCDictUnknown)
{
return;
}
CCAssert(m_eDictType == kCCDictStr, "this dictionary does not use string as its key");
CCAssert(m_eDictType == kCCDictStr, "this dictionary doesn't use string as its key");
CCAssert(key.length() > 0, "Invalid Argument!");
CCDictElement *pElement = NULL;
HASH_FIND_STR(m_pElements, key.c_str(), pElement);
@ -213,11 +275,12 @@ void CCDictionary::removeObjectForKey(const std::string& key)
void CCDictionary::removeObjectForKey(int key)
{
if (m_eOldDictType == kCCDictUnknown)
if (m_eDictType == kCCDictUnknown)
{
return;
}
CCAssert(m_eDictType == kCCDictInt, "this dictionary does not use integer as its key");
CCAssert(m_eDictType == kCCDictInt, "this dictionary doesn't use integer as its key");
CCDictElement *pElement = NULL;
HASH_FIND_INT(m_pElements, &key, pElement);
removeObjectForElememt(pElement);

340
cocos2dx/cocoa/CCDictionary.h
View File

@ -1,5 +1,5 @@
/****************************************************************************
Copyright (c) 2010 cocos2d-x.org
Copyright (c) 2012 - 2013 cocos2d-x.org
http://www.cocos2d-x.org
@ -39,142 +39,370 @@ class CCDictionary;
* @{
*/
/**
* CCDictElement is used for traversing CCDictionary.
*
* A CCDictElement is one element of CCDictionary, it contains two properties, key and object.
* 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).
* @code
* 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();
* // ......
* }
* @endcode
*
*/
class CC_DLL CCDictElement
{
#define MAX_KEY_LEN 256
private:
/**
* Constructor of CCDictElement. It's only for internal usage. CCDictionary is its friend class.
*
* @param pszKey The string key of this element.
* @param pObject The object of this element.
*/
CCDictElement(const char* pszKey, CCObject* pObject);
/**
* Constructor of CCDictElement. It's only for internal usage. CCDictionary is its friend class.
*
* @param iKey The integer key of this element.
* @param pObject The object of this element.
*/
CCDictElement(intptr_t iKey, CCObject* pObject);
public:
CCDictElement(const char* pszKey, CCObject* pObject)
{
init();
m_pObject = pObject;
/**
* The destructor of CCDictElement.
*/
~CCDictElement();
const char* pStart = pszKey;
int len = strlen(pszKey);
if (len > MAX_KEY_LEN )
{
char* pEnd = (char*)&pszKey[len-1];
pStart = pEnd - (MAX_KEY_LEN-1);
}
strcpy(m_szKey, pStart);
}
CCDictElement(intptr_t iKey, CCObject* pObject)
{
init();
m_iKey = iKey;
m_pObject = pObject;
}
// Inline functions need to be implemented in header file on Android.
/**
* Get the string key of this element.
* @note This method assumes you know the key type in the element.
* If the element's key type is integer, invoking this method will cause an assert.
*
* @return The string key of this element.
*/
inline const char* getStrKey() const
{
CCAssert(m_szKey[0] != '\0', "Should not call this function for integer dictionary");
return m_szKey;
}
/**
* Get the integer key of this element.
* @note This method assumes you know the key type in the element.
* If the element's key type is string, invoking this method will cause an assert.
*
* @return The integer key of this element.
*/
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;
}
/**
* Get the object of this element.
*
* @return The object of this element.
*/
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]; /** hash key of string type*/
intptr_t m_iKey; /** hash key of integer type */
CCObject* m_pObject;/** hash value */
// The max length of string key.
#define MAX_KEY_LEN 256
// 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 hashable */
friend class CCDictionary;
UT_hash_handle hh; // makes this class hashable
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; \
HASH_ITER(hh, (__dict__)->m_pElements, __el__, pTmp##__dict__##__el__)
/**
* CCDictionary is a class like NSDictionary in Obj-C .
*
* @note Only the pointer of CCObject or its subclass can be inserted to CCDictionary.
* @code
* // 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:
/**
* The constructor of CCDictionary.
*/
CCDictionary();
/**
* The destructor of CCDictionary
*/
~CCDictionary();
/// return the number of items
/**
* Get the count of elements in CCDictionary.
*
* @return The count of elements.
*/
unsigned int count();
/// return all the keys
/**
* Return all keys of elements.
*
* @return The array contains all keys of elements. It's an autorelease object yet.
*/
CCArray* allKeys();
/** @warning : We use '==' to compare two objects*/
/**
* Get all keys according to the specified object.
* @warning We use '==' to compare two objects
* @return The array contains all keys for the specified object. It's an autorelease object yet.
*/
CCArray* allKeysForObject(CCObject* object);
/**
* Get the object according to the specified string key.
*
* @note The dictionary needs to use string as key. If integer is passed, an assert will appear.
* @param key The string key for searching.
* @return The object matches the key. You need to force convert it to the type you know.
* @code
* // Assume that the elements are CCString* pointers. Convert it by following code.
* CCString* pStr = (CCString*)pDict->objectForKey("key1");
* // Do something about pStr.
* // If you don't know the object type, properly you need to use dynamic_cast<SomeType*> to check it.
* CCString* pStr2 = dynamic_cast<CCString*>(pDict->objectForKey("key1"));
* if (pStr2 != NULL) {
* // Do something about pStr2
* }
* @endcode
* @see objectForKey(int)
*/
CCObject* objectForKey(const std::string& key);
/**
* Get the object according to the specified integer key.
*
* @note The dictionary needs to use integer as key. If string is passed, an assert will appear.
* @param key The integer key for searching.
* @return The object matches the key.
* @see objectForKey(const std::string&)
*/
CCObject* objectForKey(int 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(int)
*/
const CCString* valueForKey(const std::string& key);
/** Get the value according to the specified integer 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(int)
*/
const CCString* valueForKey(int key);
/** Insert an object to dictionary, and match it with the specified string key.
*
* @note Whe the first time this method is invoked, the key type will be set to string.
* After that you can't setObject with an integer key.
* If the dictionary contains the key you passed, the object matching the key will be released and removed from dictionary.
* Then the new object will be inserted after that.
*
* @param pObject The Object to be inserted.
* @param key The string key for searching.
* @see setObject(CCObject*, int)
*/
void setObject(CCObject* pObject, const std::string& key);
/** Insert an object to dictionary, and match it with the specified string key.
*
* @note Then the first time this method is invoked, the key type will be set to string.
* After that you can't setObject with an integer key.
* If the dictionary contains the key you passed, the object matching the key will be released and removed from dictionary.
* Then the new object will be inserted after that.
* @param pObject The Object to be inserted.
* @param key The string key for searching.
* @see setObject(CCObject*, const std::string&)
*/
void setObject(CCObject* pObject, int key);
/**
* Remove an object by the specified string key.
*
* @param key The string key for searching.
* @see removeObjectForKey(int), removeObjectsForKeys(CCArray*),
* removeObjectForElememt(CCDictElement*), removeAllObjects().
*/
void removeObjectForKey(const std::string& key);
/**
* Remove an object by the specified integer key.
*
* @param key The integer key for searching.
* @see removeObjectForKey(const std::string&), removeObjectsForKeys(CCArray*),
* removeObjectForElememt(CCDictElement*), removeAllObjects().
*/
void removeObjectForKey(int key);
/**
* Remove objects by an array of keys.
*
* @param pKeyArray The array contains keys to be removed.
* @see removeObjectForKey(const std::string&), removeObjectForKey(int),
* removeObjectForElememt(CCDictElement*), removeAllObjects().
*/
void removeObjectsForKeys(CCArray* pKeyArray);
/**
* Remove an object by an element.
*
* @param pElement The element need to be removed.
* @see removeObjectForKey(const std::string&), removeObjectForKey(int),
* removeObjectsForKeys(CCArray*), removeAllObjects().
*/
void removeObjectForElememt(CCDictElement* pElement);
/**
* Remove all objects in the dictionary.
*
* @see removeObjectForKey(const std::string&), removeObjectForKey(int),
* removeObjectsForKeys(CCArray*), removeObjectForElememt(CCDictElement*).
*/
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);
/// @}
/** Returns a random element */
/**
* Return a random object in the dictionary.
*
* @return The random object.
* @see objectForKey(int), objectForKey(const std::string&)
*/
CCObject* randomObject();
/**
* Create a dictionary.
* @return A dictionary which is an autorelease object.
* @see createWithDictionary(CCDictionary*), createWithContentsOfFile(const char*), createWithContentsOfFileThreadSafe(const char*).
*/
static CCDictionary* create();
static CCDictionary* createWithDictionary(CCDictionary* srcDict);
/**
@brief Generate a CCDictionary pointer by file
@param pFileName The file name of *.plist file
@return The CCDictionary pointer generated from the file
* Create a dictionary with an existing dictionary.
*
* @param srcDict The exist dictionary.
* @return A dictionary which is an autorelease object.
* @see create(), createWithContentsOfFile(const char*), createWithContentsOfFileThreadSafe(const char*).
*/
static CCDictionary* createWithDictionary(CCDictionary* srcDict);
/**
* Create a dictionary with a plist file.
* @param pFileName The name of the plist file.
* @return A dictionary which is an autorelease object.
* @see create(), createWithDictionary(CCDictionary*), createWithContentsOfFileThreadSafe(const char*).
*/
static CCDictionary* createWithContentsOfFile(const char *pFileName);
/*
@brief The same meaning as dictionaryWithContentsOfFile(), but it doesn't call autorelease, so the
invoker should call release().
/**
* 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);
private:
/**
* For internal usage, invoked by setObject.
*/
void setObjectUnSafe(CCObject* pObject, const std::string& key);
void setObjectUnSafe(CCObject* pObject, const int 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;
CCDictType m_eOldDictType;
};
// end of data_structure group