TC官方文档翻译02----基础API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)

/**

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

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

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

 * @translator: selfimpr

 * @mail: [email protected]

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

 */

 

工具 API 是一组方便在内存处理记录的例程 , 另外还有可扩充字符串 , array list, hash map, ordered tree 也都是很有用的 . 在 tcutil.h 中有详细的说明

描述

使用工具 api 需要引入以下头文件

#include <tcutil.h>

#include <stdlib.h>

#include <stdbool.h>

#include <stdint.h>

TCXSTR 是可扩充字符串类型 , 可扩充字符串对象使用 tcxstrnew 函数创建 , 通过 tcxstrdel 函数删除 . TCLIST 被用于数组列表 , tclistnew 和 tclistdel 分别用于数组列表的创建和删除 . TCMAP 被用于 hash map, 同样 , tcmapnew 和 tcmapdel 是创建和删除的接口 . TCTREE 是 ordered tree, 同样有 tctreenew 和 tctreedel 接口 . 为了避免内存泄露 , 在不使用的时候删除每个对象非常重要 .

基础 api

extern const char *tcversion;

常量 tcversion 包含了版本信息

extern void (*tcfatalfunc)(const char *);

         用来处理致命错误的函数指针 , 参数指定为错误消息 . 该指针初始值为 NULL, 如果是 NULL, 那么默认的处理函数会在发生致命错误时被调用 , 致命的错误指内存分配失败

void *tcmalloc(size_t size);

用于在内存中分配一个区域

‘size’ 指定要分配的内存大小 .

返回值是指向被分配区域的的指针

这个函数会处理内存分配的失败 , 由于它的返回值是通过 malloc 调用来分配的 , 所以 , 可以在不使用的使用通过调用 free 来释放 .

void *tccalloc(size_t nmemb, size_t size);

         与 tcmalloc 类似 , 不过是 calloc 的调用 , nmemb 参数表示要分配的元素的个数 .

void *tcrealloc(void *prt, size_t size);

         与 tcmalloc 类似 , 不过是 realloc 的调用 . ptr 参数表示要重新分配的内存地址 .

void *tcmemdup(const void *ptr, size_t size);

         用于复制内存块

         ptr: 指定要复制源地址

         size: 指定要复制的块的大小

返回复制得到的块的地址 .

该函数先通过 tcmalloc 分配 size 大小空间 , 然后用 memcpy 拷贝内存块 , 最后给新的内存块末尾增加了 /0, 因此返回的指针可以被直接作为字符串使用 . 由于内存块是用 malloc 分配的 , 所以在不使用的时候 , 可以通过 free 释放 .

char *tcstrdup(const void *str);

         str: 指定要复制的字符串

返回复制后的字符串地址 . 返回的指针可以用 free 释放 .

void tcfree(void *ptr);

         ptr: 要释放的指针 , 如果是 NULL, 该函数不会产生作用 .

尽管这只是对 free 的一个包装 , 但在应用中对 malloc 系列的函数还是很有用的 .