yate学习--yateclass.h--class YATE_API NamedList : public String

/**
 * This class holds a named list of named strings
 * 这个类保存一个命名字符串的命名字符串链表
 * @short A named string container class
 * @short 一个命名字符串容器类
 */
class YATE_API NamedList : public String
{
    friend class NamedIterator;
public:
    /**
     * Creates a new named list.
     * 构造函数，创建一个新的命名链表
     * @param name Name of the list - must not be NULL or empty
     * @参数name，链表的名字-不允许为NULL或者空
     */
    explicit NamedList(const char* name);

    /**
     * Copy constructor
     * 构造函数，构造函数拷贝
     * @param original Named list we are copying
     * @参数original，将要被拷贝的链表名字
     */
    NamedList(const NamedList& original);

    /**
     * Creates a named list with subparameters of another list.
     * 构造函数，创建一个命名链表，所有的子参数从另一个链表获取
     * @param name Name of the list - must not be NULL or empty
     * @参数name，链表的名字-不允许为NULL或者空
     * @param original Named list to copy parameters from
     * @参数original，从这个命名链表拷贝参数
     * @param prefix Prefix to match and remove from parameter names
     * @参数prefix，从参数名称前缀去匹配和删除
     */
    NamedList(const char* name, const NamedList& original, const String& prefix);

    /**
     * Assignment operator
     * 赋值运算符重载
     * @param value New name and parameters to assign
     * @参数value，分配新名称和参数
     * @return Reference to this NamedList
     * @返回NamedList的引用
     */
    NamedList& operator=(const NamedList& value);

    /**
     * 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 parameters
     * 获得参数的数量
     * @return Count of named strings
     * @返回命名字符串的计数
     */
    inline unsigned int length() const
	{ return m_params.length(); }

    /**
     * Get the number of non-null parameters
     * 获得参数不为空的个数
     * @return Count of existing named strings
     * @返回存在的命名字符串的计数
     */
    inline unsigned int count() const
	{ return m_params.count(); }

    /**
     * Clear all parameters
     * 清空所有的参数
     */
    inline void clearParams()
	{ m_params.clear(); }

    /**
     * Add a named string to the parameter list.
     * 增加一个命名字符串到参数列表
     * @param param Parameter to add
     * @参数param，要添加的参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& addParam(NamedString* param);

    /**
     * Add a named string to the parameter list.
     * 增加一个命名字符串到参数列表
     * @param name Name of the new string
     * @参数name，新字符串的名字
     * @param value Value of the new string
     * @参数value，新字符串的值
     * @param emptyOK True to always add parameter, false to skip empty values
     * @参数emptyOK，为true，总能添加参数，为fals，跳过空值
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& addParam(const char* name, const char* value, bool emptyOK = true);

    /**
     * Set a named string in the parameter list.
     * 设置一个命名字符串到参数链表
     * @param param Parameter to set or add
     * @参数param，要设置或者添加的参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    inline NamedList& setParam(NamedString* param)
    {
	if (param)
	    m_params.setUnique(param);
	return *this;
    }

    /**
     * Set a named string in the parameter list.
     * 设置一个命名字符串到参数链表
     * @param name Name of the string
     * @参数name，参数的名字
     * @param value Value of the string
     * @参数value，参数的值
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& setParam(const String& name, const char* value);

    /**
     * Clears all instances of a named string in the parameter list.
     * 清除所有的参数链表的命名字符串的实体
     * @param name Name of the string to remove
     * @参数name，要移除的名字
     * @param childSep If set clears all child parameters in format name+childSep+anything
     * @参数childSep，如果从格式name+childSep+anything清除所有的孩子参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& clearParam(const String& name, char childSep = 0);

    /**
     * Remove a specific parameter
     * 清除一个特殊的参数
     * @param param Pointer to parameter to remove
     * @参数param，要移除的参数的指针
     * @param delParam True to destroy the parameter
     * @参数delParam，为true 销毁这个参数对象
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& clearParam(NamedString* param, bool delParam = true);

    /**
     * Copy a parameter from another NamedList, clears it if not present there
     * 从另一个命名链表拷贝参数，如果不存在就清理它
     * @param original NamedList to copy the parameter from
     * @参数original，从命名链表拷贝参数
     * @param name Name of the string to copy or clear
     * @参数name，要拷贝或者清理字符串的名字
     * @param childSep If set copies all child parameters in format name+childSep+anything
     * @参数childSep，如果从格式name+childSep+anything清除所有的孩子参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& copyParam(const NamedList& original, const String& name, char childSep = 0);

    /**
     * Copy all parameters from another NamedList, does not clear list first
     * 从另一个命名链表拷贝参数，先不清理链表
     * @param original NamedList to copy the parameters from
     * @参数original，从命名链表拷贝参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& copyParams(const NamedList& original);

    /**
     * Copy multiple parameters from another NamedList, clears them if not present there
     * 从另一个命名链表拷贝多个参数，如果不存在就清理它
     * @param original NamedList to copy the parameters from
     * @参数original，从命名链表拷贝参数
     * @param list List of objects (usually String) whose name (blanks stripped) is used as parameters names
     * @参数list，对象列表(通常是字符串)的名字(空格剥夺)作为参数的名称
     * @param childSep If set copies all child parameters in format name+childSep+anything
     * @参数childSep，如果从格式name+childSep+anything清除所有的孩子参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& copyParams(const NamedList& original, ObjList* list, char childSep = 0);

    /**
     * Copy multiple parameters from another NamedList, clears it if not present there
     * 从另一个命名链表拷贝多个参数，先不清理链表
     * @param original NamedList to copy the parameter from
     * @参数original，从命名链表拷贝参数
     * @param list Comma separated list of parameters to copy or clear
     * @参数list，逗号分隔的参数列表复制或清理
     * @param childSep If set copies all child parameters in format name+childSep+anything
     * @参数childSep，如果从格式name+childSep+anything清除所有的孩子参数
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& copyParams(const NamedList& original, const String& list, char childSep = 0);

    /**
     * Copy subparameters from another list
     * 拷贝另一个链表的子参数
     * @param original Named list to copy parameters from
     * @参数original，从命名链表拷贝参数
     * @param prefix Prefix to match in parameter names, must not be NULL
     * @参数prefix，匹配参数名字的前缀，不允许为NULL
     * @param skipPrefix Skip over the prefix when building new parameter name
     * @参数skipPrefix，当构建一个新的参数名的时候跳过前缀
     * @param replace Set to true to replace list parameter instead of adding a new one
     * @参数replace，设置为ture，替换新添加的被替换的参数链表
     * @return Reference to this NamedList
     * @返回命名链表的引用
     */
    NamedList& copySubParams(const NamedList& original, const String& prefix,
	bool skipPrefix = true, bool replace = false);

    /**
     * Check if we have a parameter that starts with prefix
     * 核查参数列表的前缀
     * @param prefix Prefix to match in parameter name, must not be NULL
     * @参数prefix，匹配参数名字的前缀，不允许为NULL
     * @return True if a parameter starts with prefix
     * @返回为true，如果参数从前缀开始
     */
    bool hasSubParams(const char* prefix) const;

    /**
     * Get the index of a named string in the parameter list.
     * 获得一个从参数链表中命名字符串的索引
     * @param param Pointer to the parameter to locate
     * @参数param，定位参数链表的指针
     * @return Index of the named string or -1 if not found
     * @返回命名字符串的索引，或者-1，没有找到
     */
    int getIndex(const NamedString* param) const;

    /**
     * Get the index of first matching named string in the parameter list.
     * 获得一个从参数链表中第一个匹配到的命名字符串
     * @param name Name of parameter to locate
     * @参数name，定位参数链表的名字
     * @return Index of the first matching named string or -1 if not found
     * @返回第一个匹配到命名字符串的索引，或者-1，没有找到
     */
    int getIndex(const String& name) const;

    /**
     * Locate a named string in the parameter list.
     * 从参数链表中定位一个命名字符串
     * @param name Name of parameter to locate
     * @参数name，定位参数链表的名字
     * @return A pointer to the named string or NULL.
     * @返回命名字符串的指针或者NULL
     */
    NamedString* getParam(const String& name) const;

    /**
     * Locate a named string in the parameter list.
     * 从参数链表中定位一个命名字符串
     * @param index Index of the parameter to locate
     * @参数index，检索参数链表的索引
     * @return A pointer to the named string or NULL.
     * @返回命名字符串的指针或者NULL
     */
    NamedString* getParam(unsigned int index) const;

    /**
     * Parameter access operator
     * 参数对象存取操作符重载
     * @param name Name of the parameter to return
     * @参数name，返回的参数名字
     * @return String value of the parameter, @ref String::empty() if missing
     * @返回参数的字符串值，如果为没有返回空字符串对象
     */
    const String& operator[](const String& name) const;

    /**
     * Retrieve the value of a named parameter.
      * 从参数链表检索一个值
     * @param name Name of parameter to locate
     * @参数name，要定位的参数名字
     * @param defvalue Default value to return if not found
     * @参数defvalue，如果没有找到返回的默认值
     * @return The string contained in the named parameter or the default
     * @返回命名参数的包含的字符串，或者默认值
     */
    const char* getValue(const String& name, const char* defvalue = 0) const;

    /**
     * Retrieve the numeric value of a parameter.
     * 从参数链表检索一个数值型的值
     * @param name Name of parameter to locate
     * @参数name，要定位的参数名字
     * @param defvalue Default value to return if not found
     * @参数defvalue，如果没有找到返回的默认值
     * @param minvalue Minimum value allowed for the parameter
     * @参数minvalue，参数允许的最小值
     * @param maxvalue Maximum value allowed for the parameter
     * @参数maxvalue，参数允许的最大值
     * @param clamp Control the out of bound values: true to adjust to the nearest
     *  bound, false to return the default value
     * @参数clamp，控制的绑定值:真调整到最近的绑定,假返回默认值
     * @return The number contained in the named parameter or the default
     * @返回命名参数的包含的数字，或者默认值
     */
    int getIntValue(const String& name, int defvalue = 0, int minvalue = INT_MIN,
	int maxvalue = INT_MAX, bool clamp = true) const;

    /**
     * Retrieve the numeric value of a parameter trying first a table lookup.
     * 从参数检索第一个查看的表的数值型的值
     * @param name Name of parameter to locate
     * @参数name，要定位的参数名字
     * @param tokens A pointer to an array of tokens to try to lookup
     * @参数tokens，要查找的数组的指针
     * @param defvalue Default value to return if not found
     * @参数defvalue，如果没有找到返回的默认值
     * @return The number contained in the named parameter or the default
     * @返回命名参数的包含的数字，或者默认值
     */
    int getIntValue(const String& name, const TokenDict* tokens, int defvalue = 0) const;

    /**
     * Retrieve the floating point value of a parameter.
     * 从参数中获取一个浮点型值
     * @param name Name of parameter to locate
     * @参数name，要定位的参数名字
     * @param defvalue Default value to return if not found
     * @参数defvalue，没有找到时默认返回值
     * @return The number contained in the named parameter or the default
     * @返回命名参数的包含的数字，或者默认值
     */
    double getDoubleValue(const String& name, double defvalue = 0.0) const;

    /**
     * Retrieve the boolean value of a parameter.
     * 从参数中获取一个布尔型值
     * @param name Name of parameter to locate
     * @参数name，要定位的参数名字
     * @param defvalue Default value to return if not found
     * @参数defvalue，没有找到时默认返回值
     * @return The boolean value contained in the named parameter or the default
     * @返回命名参数的包含的布尔值，或者默认值
     */
    bool getBoolValue(const String& name, bool defvalue = false) const;

    /**
     * Replaces all ${paramname} in a String with the corresponding parameters
     * 替换所有的参数名与相应的参数字符串
     * @param str String in which the replacements will be made
     * @参数str，替换的字符串
     * @param sqlEsc True to apply SQL escaping to parameter values
     * @参数sqlEsc，为true,应用SQL到参数值 
     * @param extraEsc Character to escape other than the SQL default ones
     * @参数extraEsc，缺省值
     * @return Number of replacements made, -1 if an error occured
     * @返回数字，替换的字符，-1，发生了一个错误
     */
    int replaceParams(String& str, bool sqlEsc = false, char extraEsc = 0) const;

    /**
     * Dumps the name and all parameters to a string in a human readable format.
     * 转化名字和所有的参数为可读的格式的字符串
     * No escaping takes place so this method should be used for debugging only
     * 没有转义发生这种方法只能用于调试
     * @param str String to which the name and parameters are appended
     * @参数str，附加的名称和参数字符串
     * @param separator Separator string to use before each parameter
     * @参数separator，使用之前每个参数分隔符字符串
     * @param quote String quoting character, usually single or double quote
     * @参数quote，字符串引用字符,通常单引号或双引号
     * @param force True to insert the separator even in an empty string
     * @参数force，为true，插入一个分隔符，即使是空的字符串
     */
    void dump(String& str, const char* separator, char quote = 0, bool force = false) const;

    /**
     * A static empty named list
     * 一个静态的空的命名链表 
     * @return Reference to a static empty named list
     * @返回静态的空的命名链表的引用 
     */
    static const NamedList& empty();

    /**
     * Get the parameters list
     * 获得参数链表
     * @return Pointer to the parameters list
     * @返回指向参数链表的指针
     */
    inline ObjList* paramList()
	{ return &m_params; }

    /**
     * Get the parameters list
     * 获得参数链表
     * @return Pointer to the parameters list
     * @返回指向参数链表的指针
     */
    inline const ObjList* paramList() const
	{ return &m_params; }

private:
    NamedList(); // no default constructor please
    ObjList m_params;
};