SeanLib系列函数库-MyList

1. 本篇内容

本篇介绍链表库，这是一个轻量型的带头节点的双向循环链表结构，提供了完整的链表操作接口，包含新建链表（头节点）、增加节点、搜索节点、删除节点四种方法。每个节点都拥有一个万能指针可存储任意对象。

2. 使用说明

链表结构：

c 复制代码

typedef struct _MyList_t														//定义一个双向带头节点的循环链表类型
{
	struct _MyList_t 		*Previous;											//本节点的前一个节点
	
	struct _MyList_t 		*Next;												//本节点的后一个节点
	
	void 					*Object;											//本节点的存储对象，任意类型的指针
	
}MyList_t;

所谓链表，即是每个节点被一条链子串联起来，每个节点除了存储一个目标对象外，还分别记录了它所在位置的前一个和后一个节点，因此形成了链式存储结构，从任意一个节点着手，都可以遍历到该链表中的全部节点。

以下是本库提供的链表的操作方法：

c 复制代码

/*******************************************************************************
* 功  能: 创建一个新的链表，并返回其头节点
* 参  数: 无
* 返回值：创建成功返回链表指针，否则返回空指针NULL
*******************************************************************************/
MyList_t * NewMyList(void);

/*******************************************************************************
* 功  能: 创建一个新节点并链接接到链表的尾部
* 参  数: 
*       HeadNode ：链表指针，指定一个链表的头节点
*       Object   ：要创建的新节点，任意类型的对象
* 返回值：创建成功返回节点指针，否则返回空指针NULL
*******************************************************************************/
MyList_t * MyList_AddNode(MyList_t * HeadNode, void * Object);

/*******************************************************************************
* 功  能: 根据指定的对象，在链表中搜索节点
* 参  数: 
*       HeadNode ：链表指针，指定一个链表的头节点
*       Object   ：要搜索的对象，任意类型的指针
* 返回值：若搜索到返回节点指针，否则返回空指针NULL
*******************************************************************************/
MyList_t * MyList_Search(MyList_t * HeadNode, void * Object);

/*******************************************************************************
* 功  能: 删除并释放指定的节点
* 参  数: 
*       ListNode ：节点指针，指定要删除的节点
* 返回值：无
*******************************************************************************/
void MyList_Remove(MyList_t * ListNode);

/*******************************************************************************
* 功  能: 删除并释放链表及其所有节点
* 参  数: 
*       HeadNode ：指定要删除的链表头节点
* 返回值：无
*******************************************************************************/
void MyList_Dispose(MyList_t * HeadNode);

3. 示例代码

假如要创建一个存储学生信息的链表：

c 复制代码

// 定义数据结构
typedef struct
{
	int ID;
	char Name[32];
} Student_t;

// 创建链表
MyList_t * StudentList = NewMyList();
if (StudentList == NULL)
{
	printf("链表创建失败\r\n");
	return;
}

// 添加学生数据
Student_t Student1 = {1001, "张三"};
Student_t Student2 = {1002, "李四"};
Student_t Student3 = {1003, "王五"};

MyList_AddNode(StudentList, &Student1);
MyList_AddNode(StudentList, &Student2);
MyList_AddNode(StudentList, &Student3);

// 搜索学生
MyList_t * Node = MyList_Search(StudentList, &Student2);
if (Node != NULL)
{
	Student_t * pStu = (Student_t *)Node->Object;
	printf("找到学生：%d - %s\r\n", pStu->ID, pStu->Name);
}

// 删除学生
MyList_Remove(Node);

// 释放链表
MyList_Dispose(StudentList);
StudentList = NULL;

4. 注意事项

头节点不存储数据，Object成员始终为NULL
链表为循环结构，遍历时注意结束条件（cur != HeadNode）
存储的对象指针需要确保生命周期长于链表节点
不要在回调函数或中断中执行耗时的链表操作
多线程环境下使用需自行添加同步保护