/**
* A simple single-linked object list handling class
* 一个简单的单键对象列表处理类
* @short An object list class
* @short 一个对象列表类
*/
class YATE_API ObjList : public GenObject
{
YNOCOPY(ObjList); // no automatic copies please
public:
/**
* Creates a new, empty list.
* 构造函数，创建一个新的、空的链表
*/
ObjList();
/**
* Destroys the list and everything in it.
* 析构函数，销毁链表和其中的一切
*/
virtual ~ObjList();
/**
* Get a pointer to a derived class given that class name
* 获得指向基于类名的派生类的指针
* @param name Name of the class we are asking for
* @参数name，我们要求的类名
* @return Pointer to the requested class or NULL if this object doesn't implement it
* @返回指向被请求类的指针，或者为NULL，如果这个对象没有实例化
*/
virtual void* getObject(const String& name) const;
/**
* Get the number of elements in the list
* 获得在列表中元素的数量
* @return Count of items
* @返回条目的计数
*/
unsigned int length() const;
/**
* Get the number of non-null objects in the list
* 获得列表中非空对象的个数
* @return Count of items
* @返回条目的计数
*/
unsigned int count() const;
/**
* Get the object associated to this list item
* 得到这一列表项相关联的对象
* @return Pointer to the object or NULL
* @返回对象的指针或者为NULL
*/
inline GenObject* get() const
{ return m_obj; }
/**
* Set the object associated to this list item
* 设置对象关联到这个列表项
* @param obj Pointer to the new object to set
* @参数obj，要设置的新对象的指针
* @param delold True to delete the old object (default)
* @参数delold，为true，删除旧的对象(默认为true)
* @return Pointer to the old object if not destroyed
* @返回指向就对象的指针，如果没有被销毁
*/
GenObject* set(const GenObject* obj, bool delold = true);
/**
* Get the next item in the list
* 获得列表中的下一个条目
* @return Pointer to the next item in list or NULL
* @返回指向链表中下一个条目的指针或者为NULL
*/
inline ObjList* next() const
{ return m_next; }
/**
* Get the last item in the list
* 列表中的最后一项
* @return Pointer to the last item in list
* @指向链表中最后一项的指针
*/
ObjList* last() const;
/**
* Skip over NULL holding items in the list
* 跳过空列表中的项目
* @return Pointer to the first non NULL holding item in list or NULL
* @返回指向第一个非空项在列表或NULL
*/
ObjList* skipNull() const;
/**
* Advance in the list skipping over NULL holding items
* 提前在链表中跳过空项
* @return Pointer to the next non NULL holding item in list or NULL
* @返回指向下一个非空项在列表或NULL
*/
ObjList* skipNext() const;
/**
* Get the object at a specific index in list
* 获得对象在特定的索引列表
* @param index Index of the object to retrieve
* @参数index，对象检索的索引
* @return Pointer to the object or NULL
* @返回指向对象或者NULL
*/
GenObject* at(int index) const;
/**
* Pointer-like indexing operator
* 相加赋值重载，链表拼接
* @param index Index of the list item to retrieve
* @参数index，检索链表项的索引
* @return Pointer to the list item or NULL
*/
ObjList* operator+(int index) const;
/**
* Array-like indexing operator with signed parameter
* 数组重载, 有符号的参数的索引操作符
* @param index Index of the object to retrieve
* @参数index，对象检索的索引
* @return Pointer to the object or NULL
* @返回指向对象或者NULL
*/
inline GenObject* operator[](signed int index) const
{ return at(index); }
/**
* Array-like indexing operator with unsigned parameter
* 数组重载, 无符号的参数的索引操作符
* @param index Index of the object to retrieve
* @参数index，对象检索的索引
* @return Pointer to the object or NULL
* @返回指向对象或者NULL
*/
inline GenObject* operator[](unsigned int index) const
{ return at(index); }
/**
* Array-like indexing operator
* 数组重载
* @param str String value of the object to locate
* @参数str，对象定位的字符串值
* @return Pointer to the object or NULL
* @返回指向对象或者NULL
*/
GenObject* operator[](const String& str) const;
/**
* Get the item in the list that holds an object
* 获得列表中的条目包含一个对象
* @param obj Pointer to the object to search for
* @参数obj，指向要搜索的对象的指针
* @return Pointer to the found item or NULL
* @返回指向找到的条目或者NULL
*/
ObjList* find(const GenObject* obj) const;
/**
* Get the item in the list that holds an object by String value
* 获得列表的中条目包含一个字符串值的对象
* @param str String value (toString) of the object to search
* @参数str，要搜索的对象(toString)的字符串值
* @返回指向找到的条目或者NULLfor
* @return Pointer to the found item or NULL
* @返回指向找到的条目或者NULL
*/
ObjList* find(const String& str) const;
/**
* Get the position in list of a GenObject by a pointer to it
* 获得链表中GenObject的指针的位置
* @param obj Pointer to the object to search for
* @参数obj，指向要搜索的对象的指针
* @return Index of object in list, -1 if not found
* @返回链表中对象的索引,如果没有找到返回-1
*/
int index(const GenObject* obj) const;
/**
* Get the position in list of the first GenObject with a given value
* 获得链表中GenObject的字符串的值的位置
* @param str String value (toString) of the object to search for
* @参数str，要搜索的对象(toString)的字符串值
* @return Index of object in list, -1 if not found
* @返回链表中对象的索引,如果没有找到返回-1
*/
int index(const String& str) const;
/**
* Insert an object at this point
* 插入一个对象
* @param obj Pointer to the object to insert
* @参数obj，要插入对象的指针
* @param compact True to replace NULL values in list if possible
* @参数compact，为true,如果可能在链表中替换NULL值
* @return A pointer to the inserted list item
* @返回被插入的链表条目的指针
*/
ObjList* insert(const GenObject* obj, bool compact = true);
/**
* Append an object to the end of the list
* 添加一个对象到链表的最后
* @param obj Pointer to the object to append
* @参数obj，要添加的对象的指针
* @param compact True to replace NULL values in list if possible
* @参数compact，为true,如果可能在链表中替换NULL值
* @return A pointer to the inserted list item
* @返回被插入的链表条目的指针
*/
ObjList* append(const GenObject* obj, bool compact = true);
/**
* Set unique entry in this list. If not found, append it to the list
* 设置独特的条目到链表中。如果没有找到，添加到链表中
* @param obj Pointer to the object to uniquely set in the list
* @参数obj，要设置到链表中独特的对象的指针
* @param compact True to replace NULL values in list if possible
* @参数compact，为true,如果可能在链表中替换NULL值
* @return A pointer to the set list item
* @返回被设置的链表条目的指针
*/
ObjList* setUnique(const GenObject* obj, bool compact = true);
/**
* Delete this list item
* 删除链表项
* @param delobj True to delete the object (default)
* @参数delobj，为true，删除这个对象(默认)
* @return Pointer to the object if not destroyed
* @返回返回对象的指针如果没有被销毁
*/
GenObject* remove(bool delobj = true);
/**
* Delete the list item that holds a given object
* 删除给定对象的列表项
* @param obj Object to search in the list
* @参数obj，要在链表中查找的对象
* @param delobj True to delete the object (default)
* @参数delobj，为true，删除这个对象(默认)
* @return Pointer to the object if not destroyed
* @返回返回对象的指针如果没有被销毁
*/
GenObject* remove(GenObject* obj, bool delobj = true);
/**
* Delete the first list item that holds an object with a iven value
* 删除给定字符串对象的第一个链表项
* @param str String value (toString) of the object to remove
* @参数str，要删除的对象(toString)的字符串值
* @param delobj True to delete the object (default)
* @参数delobj，为true，删除这个对象(默认)
* @return Pointer to the object if not destroyed
* @返回返回对象的指针如果没有被销毁
*/
GenObject* remove(const String& str, bool delobj = true);
/**
* Clear the list and optionally delete all contained objects
* 清除列表并选择删除所有包含的对象
*/
void clear();
/**
* Remove all empty objects in the list
* 删除所有空列表中的对象
*/
void compact();
/**
* Get the automatic delete flag
* 获得自动删除的标志
* @return True if will delete on destruct, false otherwise
* @返回为true，如果被删除的时候销毁，否则为false
*/
inline bool autoDelete()
{ return m_delete; }
/**
* Set the automatic delete flag
* 设置自动删除的标志
* @param autodelete True to delete on destruct, false otherwise
* @参数autodelete，为true，如果被删除的时候销毁，否则为false
*/
inline void setDelete(bool autodelete)
{ m_delete = autodelete; }
/**
* A static empty object list
* 一个静态的空的对象链表
* @return Reference to a static empty list
* @返回静态的空的链表的引用
*/
static const ObjList& empty();
/**
* Sort this list
* 链表排序
* @param callbackCompare pointer to a callback function that should compare two objects.
* @参数callbackCompare，指向比较两个对象的回调函数的指针
* <pre>
* obj1 First object of the comparation
* obj1，第一个比较对象
* obj2 Second object of the comparation
* obj2，第二个比较对象
* context Data context
* context，上下文数据
* return 0 if the objects are equal; positive value if obj2 > obj1; negative value if obj1 > obj2
* 返回0，两个对象相等，正数，obj2 > obj1，负数，obj1 > obj2
* </pre>
* @param context Context data.
* @参数context，上下文数据
*/
void sort(int (*callbackCompare)(GenObject* obj1, GenObject* obj2, void* context), void* context = 0);
private:
ObjList* m_next;
GenObject* m_obj;
bool m_delete;
};
