Skip to main content
Version: Next 🚧

实用工具库

  • 开始日期:2021-09-28
  • 目标主要版本:3.x
  • 参考问题:无
  • 实现 PR:#264

概括

添加实用工具库,提供链表(LinkedList)、字典(Dict)、日志(Logger)等常用的数据结构和函数。

基本示例

实用工具库的构建命令:

# 构建库
xmake build yutil

# 构建测试用例
xmake build yutil_test

# 运行测试
xmake run yutil_test

list 的使用例子:

#include <yutil.h>

void test_list(void)
{
int arr[] = { 0, 4, 8, 16, 32, 64, 1024, 2048 };
size_t i;
size_t n = sizeof(arr) / sizeof(int);

//创建一个链表结构
list_t list;
//创造一个结点类型的指针
list_node_t *node;

//初始化链表
list_create(&list);

// append data
for (i = 0; i < n; ++i) {
list_append(&list, arr + i);
}

// delete data
for (i = 0; i < n; ++i) {
list_delete(&list, 0);
}

// insert data
for (i = 0; i < n; ++i) {
list_insert(&list, i, arr + i);
}

// insert head
list_insert_head(&list, 0);
// delete head
list_delete_head(&list);

list_append(&list, 0);

// delete tail
list_delete_last(&list);

//遍历
i = 0;
list_for_each(node, &list)
{
if (node->data != arr + i) {
break;
}
++i;
}

// 反向遍历
i = n - 1;
list_for_each_reverse(node, &list)
{
if (node->data != arr + i) {
break;
}
if (i == 0) {
i = n;
break;
}
--i;
}

//销毁链表
list_destroy(&list, NULL);
}

动机

详细设计

参考 glib、tbox 设计 API,将一些工具类函数整理进独立的子库中,子库命名为易工具(yutil),提供以下功能模块:

  • list: 列表。基于双向链表实现,由列表元素在内部维护的链表节点。
  • list_entry: 双向循环链表。链表节点不包含数据,使用时需将链表节点添加为元素数据结构成员。
  • rbtree: 红黑树。
  • dict: 字典(哈希表)。基于 2021年 8 月为止最新的 redis 中的 dict 代码做修改。
  • string: 提供一些额外的字符串操作函数,包括:转换成小写、生成哈希值、分割字符串、清除字符串首尾的字符。
  • strpool: 字符串池。用于解决大量相同字符串的内存占用问题。
  • strlist: 字符串列表。针对部件和 CSS 选择器的多字符串存储需求而设计,配合 strpool 使用。
  • logger: 日志输出和管理。提供日志输出和按级别过滤。
  • timer: 定时器。用法是维护一个定时器列表,每次调用处理函数时获取已过期的定时器,并调用相应的回调函数。
  • dirent: 目录操作相关函数。
  • charset: UTF-8 编码和解码。
  • time: 提供高精度时间相关接口。
  • math: 提供一些额外的数学运算操作,包括最大、最小和取整函数。

删除原 src/util 目录中的以下文件:

  • parse.c:字符串解析功能只有 CSS 库在用,应该由 CSS 库内部包含它。
  • object.c:主要用于实现 UI 和数据的双向绑定,属于实验性的功能,3.x 版本暂时不需要考虑它。
  • task.c:用于与工作线程的任务处理,应该包含到工作线程库中。
  • event.c:UI 和主循环都用到了事件机制,这块应该由它们内部实现。
  • rect.c:矩形数据结构有浮点型和整型这两个版本,分别用于 UI 库和图形库,它应该由这两个库内部实现。
  • steptimer.c:依赖线程库的互斥锁和条件变量操作函数,不适合放入工具库内,应该考虑由平台库提供。
  • uri.c/uri.cpp:URI 的打开函数属于操作系统接口,应该由平台库提供。

子库是贡献者 @yidianyiko 开发的一个独立的开源项目,因此以 git 子模块的方式引入,而不是直接将它的源码整合进 LCUI 项目内。

具体细节可查阅以下文档:

缺点

无。

备选方案

直接使用 glib、tbox。缺点是改动量比 yutil 要大,而且会增加 LCUI 项目的体积和构建配置复杂度。

采用策略

这是个破坏性改动,需要对所有用到工具函数的代码进行修改。由于主要改动都在命名上,这些文件通常只需要全局替换名称即可。

未解决的问题

标准库已经提供字符编解码函数 wcstombs() 和 mbstowcs(),charset 模块存在意义不大,应该考虑移除。

math 提供的最大、最小和取整函数用途不大,应该考虑移除它们。

rbtree 在 LCUI 内的用途很少,应该考虑移除它,用 dict 代替。

string 模块中的一些函数的通用性较差,应该考虑移出去,作为内部函数。

time 模块中的 sleep() 函数与 Linux 提供的 sleep() 存在名称冲突,应该考虑调整命名。

移除 bool_t?