/*******************************************************************************
** 文件名称：gm_list.h
** 文件作用：链表通用操作头文件
** 编写作者：Tom Free 付瑞彪
** 编写时间：2018-08-25
** 文件备注：
**          1、通用链表操作，双向循环链表，头节点为管理节点，不存放用户数据，仅提供给链表
**             管理器使用
**          2、提供动态链表管理器创建，可以使用 GM_LinkedList_Create 函数进行创建，如
**             不需动态创建可直接采用静态或全局变量创建，也可用户自己采用动态内存进行创建
**          3、用户必需将 GM_LinkedListNode 型的一个变量放入结构体起始处来构建链表管理
**             数据，不可放置在结构体其它地方，本文件未提供相关函数或宏来进行索引
**
**          Note:若要查看相关帮助或例程请参考此文件夹下的ReadMe.md文件
**
** 更新记录：
**          2018-08-25 -> 创建文件                                   <Tom Free>
**          2018-08-30 -> 架构重新布局，采用更好的管理方式              <Tom Free>
**
**          1 Tab == 4 Spaces     UTF-8     ANSI C Language
*******************************************************************************/
#ifndef __GM_LIST_H__
#define __GM_LIST_H__

/* 通用数据类型定义头文件 */
#include "./GM_Type/gm_type.h"

/* 链表定义，用于隐藏数据，防止用户过于关心内部数据结构 */
#define GM_LIST     void*

/*******************************************************************************
** 函数名称：GM_LinkedList_Create
** 函数作用：链表创建
** 输入参数：无
** 输出参数：创建的链表指针，GM_NULL - 创建失败
** 使用范例：GM_LinkedList* pxNewLinkedList = GM_LinkedList_Create();
** 函数备注：创建成功后会进行初始化
*******************************************************************************/
GM_LIST* GM_List_Create();

/*******************************************************************************
** 函数名称：GM_LinkedList_Init
** 函数作用：链表初始化
** 输入参数：pxLinkedList - 待初始化链表参数，也可作为链表的清空操作
** 输出参数：初始化是否成功
** 使用范例：GM_BOOL emResult = GM_LinkedList_Init(&xLinkedList);
** 函数备注：链表不存在时会返回错误
*******************************************************************************/
GM_BOOL GM_LinkedList_Init(GM_LIST* const pxLinkedList);

/*******************************************************************************
** 函数名称：GM_LinkedList_AddToTail
** 函数作用：向链表尾部添加节点
** 输入参数：pxLinkedList - 链表
**          pxNode       - 待插入节点
** 输出参数：插入是否成功
** 使用范例：GM_BOOL emResult = GM_LinkedList_AddToTail(&xLinkedList, &xNode);
** 函数备注：此节点若是已在链表中，返回错误，否则进行添加
*******************************************************************************/
GM_BOOL GM_List_AddToTail(GM_LIST* const pxLinkedList,
                                  GM_LIST_NODE* const pxNode);

/*******************************************************************************
** 函数名称：GM_LinkedList_AddToHead
** 函数作用：向链表头部添加节点
** 输入参数：pxLinkedList - 链表
**          pxNode       - 待插入节点
** 输出参数：插入是否成功
** 使用范例：GM_BOOL emResult = GM_LinkedList_AddToHead(&xLinkedList, &xNode);
** 函数备注：此节点若是已在链表中，返回错误，否则进行添加
*******************************************************************************/
GM_BOOL GM_LinkedList_AddToHead(GM_LIST* const pxLinkedList,
                                  GM_LIST_NODE* const pxNode);

/*******************************************************************************
** 函数名称：GM_LinkedList_Delete
** 函数作用：从链表中删除节点
** 输入参数：pxLinkedList - 链表
**          pxNode       - 待删除节点
** 输出参数：删除是否成功
** 使用范例：GM_BOOL emResult = GM_LinkedList_Delete(&xLinkedList, &xNode);
** 函数备注：此节点如果是已在链表中的节点，会删除，如果不在链表中，不执行删除，并返回错误
*******************************************************************************/
GM_BOOL GM_LinkedList_Delete(GM_LIST* const pxLinkedList,
                               GM_LIST_NODE* const pxNode);

/*******************************************************************************
** 函数名称：GM_LinkedList_NodeInList
** 函数作用：判断节点是否在链表中
** 输入参数：pxLinkedList - 链表
**          pxNode       - 节点
** 输出参数：GM_TRUE - 节点在链表中，GM_FALSE - 节点不在链表中
** 使用范例：GM_BOOL blResult = GM_LinkedList_NodeInList(&xLinkedList, &xNode);
** 函数备注：
*******************************************************************************/
GM_BOOL GM_LinkedList_NodeInList(GM_LIST* const pxLinkedList,
                                 GM_LIST_NODE* const pxNode);

/*******************************************************************************
** 函数名称：GM_LinkedList_GetListLength
** 函数作用：获取链表长度
** 输入参数：pxLinkedList - 链表
** 输出参数：GM_TRUE - 节点在链表中，GM_FALSE - 节点不在链表中
** 使用范例：size_t num = GM_LinkedList_GetListLength(&xLinkedList);
** 函数备注：不包括头节点，头节点非用户使用，不算在链表长度之内
*******************************************************************************/
GM_SIZE GM_LinkedList_GetListLength(GM_LIST* const pxLinkedList);

/**************************** 外部接口声明结束 **********************************/
/******************************************************************************/

#endif  /* GM_LINKED_LIST_H */