yate学习--yateclass.h--class YATE_API ObjList : public GenObject

/**
 * 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;
};