Redis 2.8.9源码 - 字符串操作函数头整理，并注释作用和参数说明

本文为作者原创，转载请注明出处：http://my.oschina.net/fuckphp/blog/269119

Redis sds 字符串测试方法：

gcc zmalloc.c sds.c -D SDS_TEST_MAIN

函数头说明：

/**
 * 根据sds值获取字符串对象的已占用长度
 * sds s sds值
 * return 返回字符串对象的已占用长度
 */
static inline size_t sdslen(const sds s);


/**
 * 根据sds值获取字符串对象的剩余空间
 * sds s 字符串对象的sds值
 * return 返回字符串对象的剩余空间
 */
static inline size_t sdsavail(const sds s)


/**
 * 根据 initlen 创建一个新的字符串对象
 * void *init 字符串对象的sds值
 * size_t initlen 创建字符串对象的字符串长度
 * return 返回sds值
 */
sds sdsnewlen(const void *init, size_t initlen);


/**
 * 创建一个空的字符串对象
 * return 返回sds值
 */
sds sdsempty(void);


/**
 * 根据字符串创建一个字符串对象
 * void *init 字符串对象的sds值
 * return 返回sds值
 */
sds sdsnew(const char *init);


/**
 * 为传入的sds对象创建一个副本
 * sds s 字符串对象的sds值
 * return 返回sds值
 */
sds sdsdup(const sds s); 


/**
 * 根据sds释放sds对应字符串对象的空间
 * sds s 需要释放的字符串对象的sds值
 * return void
 */
void sdsfree(sds s); 


/**
 * 根据sds值的实际情况，更新字符串对象 free 和 len属性
 * sds s 字符串对象的sds值
 * return void
 */
void sdsupdatelen(sds s);


/**
 * 将传入的sds对象清空，只清空内容不释放内存
 * sds s 字符串对象的sds值
 * return void
 */
 void sdsclear(sds s);


/**
 * 将sds对应的字符串对象的空间扩展addlen字节
 * sds s 字符串对象的sds值
 * size_t addlen 需要扩展的字节数
 * return 返回更新后的sds值
 */
sds sdsMakeRoomFor(sds s, size_t addlen);


/**
 * 将sds对应的字符串对象free部分释放掉，并将free更新为0
 * sds s 字符串对象的sds值
 * return 返回更新后的sds值
 */
sds sdsRemoveFreeSpace(sds s);


/**
 * 获取sds对应的字符串对象所占用的总空间 (sdshdr结构大小 + sdshdr->len + sdshdr->free + 1)
 * sds s 字符串对象的sds值
 * return 返回sds对应的字符串对象所占用的总空间
 */
 size_t sdsAllocSize(sds s);


/**
 * 根据incr参数更新sds对应字符窜对象的len和free属性
 * sds s 字符串对象的sds值
 * int incr 增加的占用空间的字节数
 * return void
 */
 void sdsIncrLen(sds s, int incr);


/**
 * 将sds对应的字符串对象所占用空间增加到len长度，并将未使用部分设置为0
 * sds s 字符串对象的sds值
 * size_t len 增加的占用空间的字节数
 * return 返回更新后的sds值
 */
sds sdsgrowzero(sds s, size_t len);


/**
 * 根据字符串长度将指定字符串追加到sds值的后面
 * sds s 字符串对象的sds值
 * void *t 追加的内容
 * size_t len 追加内容的长度
 * return 返回更新后的sds值
 */
sds sdscatlen(sds s, const void *t, size_t len);


/**
 * 将指定字符串追加到sds值的后面
 * sds s 字符串对象的sds值
 * void *t 追加的内容
 * return 返回更新后的sds值
 */
sds sdscat(sds s, const char *t);


/**
 * 将一个sds值追加到另一个sds值的后面
 * sds s 字符串对象的sds值
 * sds t 追加的sds内容
 * return 返回更新后的sds值
 */
sds sdscatsds(sds s, const sds t);



/**
 * 将指定长度的字符串复制到sds值上，会覆盖原sds值
 * sds s 字符串对象的sds值
 * char *t 需要覆盖的字符串
 * size_t len 需要覆盖的字符串长度
 * return 返回更新后的sds值
 */
sds sdscpylen(sds s, const char *t, size_t len);


/**
 * 将指定字符串复制到sds值上，会覆盖原sds值
 * sds s 字符串对象的sds值
 * char *t 需要覆盖的字符串
 * return 返回更新后的sds值
 */
sds sdscpy(sds s, const char *t);


/**
 * 根据fmt格式化字符串和指定的可变参数将格式化后的数据追加到sds值的后面
 * sds s 字符串对象的sds值
 * char *fmt 格式化字符串
 * ... N个格式化字符串参数
 * return 返回更新后的sds值
 */
sds sdscatprintf(sds s, const char *fmt, ...);


/**
 * 根据fmt格式化字符串和指定的va_list将格式化后的数据追加到sds值的后面
 * sds s 字符串对象的sds值
 * char *fmt 格式化字符串
 * va_list ap个格式化字符串参数
 * return 返回更新后的sds值
 */
sds sdscatvprintf(sds s, const char *fmt, va_list ap);


/**
 * 清除sds值两端的字符串cset
 * sds s 字符串对象的sds值
 * char *cset 需要替换掉的字符串
 * return 返回更新后的sds值
 */
sds sdstrim(sds s, const char *cset) ;


/**
 * 将sds对应的字符串对象截取为 start 到 end之间的数据
 * sds s 字符串对象的sds值
 * int start 开始位置
 * int end 结束位置
 * return void
 */
void sdsrange(sds s, int start, int end);


/**
 * 将sds值转为小写
 * sds s 字符串对象的sds值
 * return void
 */
 void sdstolower(sds s);


/**
 * 将sds值转为大写
 * sds s 字符串对象的sds值
 * return void
 */
 void sdstoupper(sds s);


/**
 * 比较两个sds值是否相等
 * sds s 字符串对象的sds值
 * return void
 */
 int sdscmp(const sds s1, const sds s2);



/**
 * 将指定长度的字符串根据指定长度的分隔符分割为sds对象的数组
 * char *s 待分割的字符串
 * int len 待分割字符串的长度
 * char *sep 分隔符
 * int seplen 分隔符长度
 * int *count 用于记录分割后的数组长度，用于释放时使用
 * return 返回分割后的sds数组
 */
sds *sdssplitlen(const char *s, int len, const char *sep, int seplen, int *count);


/**
 * 释放sdssplitlen函数的返回值
 * sds *tokens 分割后的sds数组
 * int count 需要释放的长度
 * return void
 */
void sdsfreesplitres(sds *tokens, int count);


/**
 * 根据long long的数值创建sds字符串对象
 * long long value 需要转换的长长整型值
 * return 返回创建的sds对象
 */
sds sdsfromlonglong(long long value);

/**
 * 将指定长度的字符串 进行转换后追加到sds字符串结尾，例如将不可见字符串改为可见,用于redis-cli输出等
 * sds s sds值
 * char *p 待追加的字符串
 * size_t len 带追加字符串的长度
 * return 返回转换后的sds对象
 */
sds sdscatrepr(sds s, const char *p, size_t len);



/**
 * 判断传入的字符是否是16进制字符
 * char c 待判断的字符
 * return 返回 0/1
 */
int is_hex_digit(char c);


/**
 * 将传入的16进制字符转为10进制数字
 * char c 待转换的字符
 * return 返回整型
 */
int hex_digit_to_int(char c);


/**
 * 将命令行参数处理成redis可识别的sds数组并返回argc参数数目
 * char *line 待处理的命令行参数
 * int *argc 用于返回参数数目
 * return 转换后的sds字符串数组
 */
sds *sdssplitargs(const char *line, int *argc);


/**
 * 字符串替换
 * sds s 需要处理的sds字符串
 * char *from 需要替换的字符串
 * char *to 替换后的字符串
 * size_t setlen 搜索字符串的长度
 * return 转换后的sds字符串数组
 */
sds sdsmapchars(sds s, const char *from, const char *to, size_t setlen);


/**
 * 将字符串数组根据分隔符转换为一个sds字符串
 * char **argv 带处理的字符串数组
 * int argc 待处理的字符串数组元素个数
 * char *sep 分隔符s
 * return 转换后的sds字符串数组
 */
sds sdsjoin(char **argv, int argc, char *sep);