修改函数原型说明

README.md

@@ -1,13 +1,19 @@
 # unicstl
 
 ## 简介
-全称: Universal C standard library
+基于C语言实现的通用C库，包含常用数据结构和算法。
 
-基于C语言实现的通用C库。包含常用数据结构和算法
+**全称：** Universal C standard library
 
-> 标准：--std=c99
+**作者：** 温建峰
 
-[数据结构详细说明](https://blog.wenjianfeng.top)
+**主页：** [博客](https://blog.wenjianfeng.top)
+
+**邮箱：**[orig5826@163.com](mailto:orig5826@163.com)
+
+## 编译环境
+- 编译器：gcc 13.2.0 
+- 标准：--std=c99
 
 ## 数据结构
 |数据结构 | 原理 |说明 |
@@ -27,12 +33,81 @@
 | tree_rb_new  | 二叉搜索树 | 红黑树 |
 | **heap**    | |**堆** |
 | heap_new2   | 数组 | 最大堆/最小堆 |
+| **graph**    | |**图** |
+| graph_new   | 链表 |  |
+
+## 接口函数原型
+```c
+// -------------------- 初始化 --------------------
+struct* new(...);                   // 创建
+void free(struct**);                // 释放
+
+// 内部接口
+// init 初始化  <构造函数>
+// destory 销毁 <析构函数>
+
+// 外部实现
+int compare(void* obj1, void* obj2);// 比较函数，new后立刻配置（树、图必须）
+
+// -------------------- 核心功能 --------------------
+// 核心操作
+bool push(const void* obj);         // [栈、队列] 入栈/入队
+bool push_front(const void* obj);   // [双端队列] 头部入队
+bool push_back(const void* obj);    // [双端队列] 尾部入队
+
+bool pop(void* obj);                // [栈、队列] 出栈/出队
+bool pop_front(void* obj);          // [双端队列] 头部出队
+bool pop_back(void* obj);           // [双端队列] 尾部出队
+
+bool peek(void* obj);               // [栈]            查看栈顶元素
+bool front(void* obj);              // [队列、双端队列] 查看头部元素
+bool back(void* obj);               // [队列、双端队列] 查看尾部元素
+
+// bool insert(const void* obj);       // [树] 插入元素 <insert用于和位置相关操作>
+// bool delete(const void* obj);       // [树] 删除元素
+
+// bool add_(const void* obj);         // [图：顶点、边] 添加元素 <add不考虑位置关系>
+// bool del_(const void* obj);         // [图：顶点、边] 删除元素 
+// bool find_(const void* obj);        // [图：顶点、边] 查找元素
+
+// 基础操作
+uint32_t size();                    // 获取大小
+bool empty();                       // 判断是否为空
+bool full();                        // 判断是否为满
+void clear();                       // 清空
+uint32_t capacity();                // [动态数组] 获取容量
+
+// 迭代器操作
+iterator_t iter(...);               // 返回迭代器
+bool iter_hasnext();                // 是否有下一个元素
+void* iter_next();                  // 迭代器下一个元素
+
+// -------------------- 扩展功能 --------------------
+// 元素相关操作
+bool append(const void* obj);        // 追加元素 <push_back> 一般用于list 
+bool delete(const void* obj);       // 删除元素
+// bool remove(const void *obj);     // 删除元素 <同delete>
+bool find(const void* obj);          // 查找元素 <返回值，bool/uint32_t/void*待定？>
+bool contains(const void* obj);      // 判断元素是否存在 <返回bool>
+uint32_t count(const void* obj);     // 统计元素个数
+
+// 索引相关操作
+uint32_t index(void *obj);                      // 获取元素索引
+bool insert(uint32_t index, const void* obj);   // 插入元素 <非树>
+bool erase(uint32_t index);                     // 删除元素
+bool set(uint32_t index, const void* obj);      // 设置元素
+bool get(uint32_t index, void* obj);            // 获取元素
+
+```
 
 ## 特点
-| 原理 | 说明 |
-| --- | --- |
-| 链表 | 有额外指针开销 |
-| 动态数组 | 扩容时数据搬移代价较大 |
+| 原理 | 优势 | 弊端 |
+| --- | --- |--- |
+| 链表 | 插入删除效率高 | 有额外指针开销 |
+| 动态数组 | 随机访问效率高 | 扩容时数据搬移代价较大 |
+| --- | --- | --- |
+| 单链表 | 适用内存受限场景 | 逆向不便 |
+| 双向链表 | 频繁双向遍历的场景（如光标移动） | 空间开销大 |
 
 
 ## 性能比较
@@ -91,6 +166,18 @@ unicstl_stack_v1.2.5_20240717-a0.zip
 
 ## 修改日志
 
+### Unicstl 0.0.02 (2025-04-24)
+- new features
+    - graph add function: add/del/find vertex/edge
+    - graph add function: bfs/dfs
+    - tree remove old iterator and add new iterator
+    - deque add order select
+- bugfixed: 
+    - none
+- others:
+    - none
+
+
 ### Unicstl 0.0.01 (2025-04-24)
 - new features
     - add stack

include/deque.h

@@ -13,6 +13,12 @@
 
 #include "common.h"
 
+enum _deque_order
+{
+    DEQUE_FORWARD,
+    DEQUE_REVERSE,
+};
+
 struct _deque_node
 {
     void* obj;
@@ -50,7 +56,7 @@ struct _deque
     bool (*clear)(struct _deque* self);
 
     // iter
-    iterator_t (*iter)(struct _deque* self);
+    iterator_t (*iter)(struct _deque* self, enum _deque_order order);
 
     // ohters
     bool (*insert)(struct _deque* self, int index, void* obj);

include/graph.h

@@ -78,12 +78,11 @@ struct _graph
     bool (*del_edge)(struct _graph* self, void* from, void* to);
     bool (*find_edge)(struct _graph* self, void* from, void* to);
 
-    bool (*empty)(struct _graph* self);
-    bool (*full)(struct _graph* self);
-
     // base
     uint32_t(*size)(struct _graph* self);
     uint32_t(*capacity)(struct _graph* self);
+    bool (*empty)(struct _graph* self);
+    bool (*full)(struct _graph* self);
     bool (*clear)(struct _graph* self);
 
     // iter

include/heap.h

@@ -36,12 +36,12 @@ struct _heap
 
     // -------------------- public -------------------- 
     // kernel
-    bool (*peek)(struct _heap* self, void* obj);
     bool (*push)(struct _heap* self, void* obj);
     bool (*pop)(struct _heap* self, void* obj);
-    bool (*empty)(struct _heap* self);
+    bool (*peek)(struct _heap* self, void* obj);
 
     // base
+    bool (*empty)(struct _heap* self);
     uint32_t(*size)(struct _heap* self);
     bool (*clear)(struct _heap* self);
 

include/iterator.h

@@ -20,6 +20,8 @@ struct _iterator
     void* _cur_node;
     uint32_t _cur;
 
+    uint32_t _order;
+
     // ---------- public ---------- 
     bool (*hasnext)(struct _iterator* self);
     const void* (*next)(struct _iterator* self);

include/list.h

@@ -43,6 +43,7 @@ struct _list
 
     // base
     uint32_t (*size)(struct _list *self);
+    uint32_t (*capacity)(struct _list *self);
     bool (*empty)(struct _list *self);
     bool (*clear)(struct _list *self);
 

include/stack.h

@@ -43,11 +43,11 @@ struct _stack
     bool (*push)(struct _stack* self, void* obj);
     bool (*pop)(struct _stack* self, void* obj);
     bool (*peek)(struct _stack* self, void* obj);
-    bool (*empty)(struct _stack* self);
     
     // base
     uint32_t (*size)(struct _stack* self);
     uint32_t (*capacity)(struct _stack* self);
+    bool (*empty)(struct _stack* self);
     bool (*clear)(struct _stack* self);
     
     // iter

src/deque.c

@@ -295,14 +295,22 @@ static void deque_print(struct _deque* self)
     }
 }
 
-iterator_t deque_iter(struct _deque* self)
+iterator_t deque_iter(struct _deque* self, enum _deque_order order)
 {
     assert(self != NULL);
     iterator_t iter = &self->_iter;
 
     iter->_parent = self;
     iter->_cur = 0;
+    iter->_order = order;
+    if(iter->_order == DEQUE_FORWARD)
+    {
         iter->_cur_node = self->_head;
+    }
+    else
+    {
+        iter->_cur_node = self->_tail;
+    }
     return iter;
 }
 
@@ -327,13 +335,22 @@ const void* deque_iter_next(struct _iterator* iter)
     deque_t self = (deque_t)iter->_parent;
     void *obj = NULL;
     
-    // base on linklist
-    struct _deque_node * node = (struct _deque_node *)iter->_cur_node;
-    if(node != NULL)
+    struct _deque_node * cur_node = (struct _deque_node *)iter->_cur_node;
+    if(cur_node == NULL)
     {
-        obj = node->obj;
-        iter->_cur_node = node->next;
+        return NULL;
     }
+
+    obj = cur_node->obj;
+    if(iter->_order == DEQUE_FORWARD)
+    {
+        iter->_cur_node = cur_node->next;
+    }
+    else
+    {
+        iter->_cur_node = cur_node->prev;
+    }
+
     self->_iter._cur += 1;
     return obj;
 }

test/test_deque.c

@@ -267,7 +267,7 @@ static void test_deque_struct(void)
 static void test_deque_iter(void)
 {
     uint32_t i = 0;
-    int data[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+    int data[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
     int temp = 0;
     uint32_t len = sizeof(data) / sizeof(data[0]);
 
@@ -288,26 +288,33 @@ static void test_deque_iter(void)
         TEST_ASSERT_EQUAL_INT(i + 1, deque->size(deque));
     }
 
-    iterator_t iter = deque->iter(deque);
+    iterator_t iter = deque->iter(deque, DEQUE_FORWARD);
     i = 0;
     while(iter->hasnext(iter))
     {
         temp = *(int *)iter->next(iter);
-        // printf("%d ", temp);
         TEST_ASSERT_EQUAL_INT(data[i], temp);
         i++;
     }
 
-    iter = deque->iter(deque);
+    iter = deque->iter(deque, DEQUE_FORWARD);
     i = 0;
     while(iter->hasnext(iter))
     {
         temp = *(int *)iter->next(iter);
-        // printf("%d ", temp);
         TEST_ASSERT_EQUAL_INT(data[i], temp);
         i++;
     }
 
+    iter = deque->iter(deque, DEQUE_REVERSE);
+    i = len - 1;
+    while(iter->hasnext(iter))
+    {
+        temp = *(int *)iter->next(iter);
+        TEST_ASSERT_EQUAL_INT(data[i], temp);
+        i--;
+    }
+
     deque_free(&deque);
     TEST_ASSERT_NULL(deque);
 }

test/test_graph.c

@@ -149,7 +149,7 @@ void test_graph_iter(void)
     TEST_ASSERT_TRUE(graph->add_edge(graph, &data[7], &data[6], 87));
     TEST_ASSERT_TRUE(graph->add_edge(graph, &data[8], &data[2], 92));
     TEST_ASSERT_FALSE(graph->add_edge(graph, &temp, &data[1], 0));
-    graph->print(graph);
+    // graph->print(graph);
 
     iterator_t iter_vertex = NULL;
 
@@ -158,18 +158,18 @@ void test_graph_iter(void)
     while(iter_vertex->hasnext(iter_vertex))
     {
         temp = *(int *)iter_vertex->next(iter_vertex);
-        graph->print_obj(&temp);
+        //graph->print_obj(&temp);
     }
-    printf("\n");
+    //printf("\n");
 
     iter_vertex = graph->iter(graph, GRAPH_DFS, &data[0]);
     TEST_ASSERT_NOT_NULL(iter_vertex);
     while(iter_vertex->hasnext(iter_vertex))
     {
         temp = *(int *)iter_vertex->next(iter_vertex);
-        graph->print_obj(&temp);
+        //graph->print_obj(&temp);
     }
-    printf("\n");
+    //printf("\n");
 
     graph_free(&graph);
     TEST_ASSERT_NULL(graph);