TC官方文档翻译03----可扩充字符串API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)

/**

 * 转载请注明出处, 由于个人技术能力有限, 英语水平欠缺,

 * 有翻译不合适或错误的地方, 请纠正,

 * 希望不要因为我的错误误导您, 希望您的智慧可以加入.

 * @translator: selfimpr

 * @mail: lgg860911@yahoo.com.cn

 * @blog: http://blog.csdn.net/lgg201

 */

 

可扩充字符串 API

typedef struct {

         char *ptr; // 字符串指针

         int size; // 当前字符串占用大小

         int assize; // 字符串对象当前分配的内存大小

} TCXSTR;

TCXSTR *tcxstrnew(void);

         创建一个可扩充字符串 .

         函数首先分配一个 TCXSTR 结构的内存 , 然后为其内部的 ptr 分配初始的 TCXSTRUNIT( 默认 12) 大小内存 , 设置 size 为 0, assize 为 TCXSTRUNIT, 将 ptr[0] 设置为 /0( 也就是设置为空字符串 )

TCXSTR *tcxstrnew2(const char *str);

         指定一个字符串作为初始值创建一个可扩充字符串对象

         返回的可扩充字符串对象是按照 str 量身定做 , 但是如果 str 长度加 1 小于 TCXSRUNIT 时 , 该字符串的分配内存会是 TCXSTRUNIT.

TCXSTR *tcxstrnew3(int asiz);

         指定一个初始内存大小来创建一个可扩充字符串对象 .

与 tcxstrnew 相似 , 不过在为 ptr 分配内存时 , 按照指定的 asiz 而不是 TCXSTRUNIT

TCXSTR *tcxstrdup(const TCXSTR *xstr);

         复制指定的可扩充字符串 , 但是 , 新的可扩充字符串中的 asize 是取 xstr 的 size+1 和 TCXSTRUNIT 两者的大值 .

void tcxstrdel(TCXSTR *xstr);

         释放指定的可扩充字符串对象 .

void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);

         该函数用来连接字符串 , 将 ptr 的 size 个字符连接到 xstr 字符串末尾

         函数中首先计算新字符串的长度 , 然后对 xstr 的 asize 进行扩充 ( 每次 2 倍 ) 知道其大小适合新字符串存储 , 重新分配内存 , 内存拷贝 , 然后修改 xstr 的 size, 为字符串追加字符串结束符 .

void tcxstrcat2(TCXSTR *xstr, const char *str);

         与 tcxstrcat 类似 , 不过是将 str 全部连接到 xstr 上 .

const void *tcxstrptr(const TCXSTR *xstr);

         返回可变字符串中存储的字符串的值 , 可以直接作为字符串使用 .

int tcxstrsize(const TCXSTR *xstr);

         返回当前该可扩充字符串对象中实际存储的字符串的大小

void tcxstrclear(TCXSTR *xstr);

         将指定的可扩充字符串对象中已经存储的字符串设置为空字符串 ( 直接将该指针指向 /0), 并将 xstr->size 设置为 0

char *tcxstrprintf(TCXSTR *xstr, const char*format, …);

         格式化一个可扩充字符串对象

返回的指针可以用 free 释放 .