/*
 * Copyright (c) 2000-2008
 * Author: Weiming Zhou
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  
 */

#ifndef __SINGLELIST_H__
#define __SINGLELIST_H__

#ifdef __cplusplus
extern "C" {
#endif


/* 單向鏈表的結(jié)構(gòu)體 */
typedef struct SINGLELIST_st {
	SINGLENODE	    *pHead;        /* 第1個節(jié)點的指針 */
	SINGLENODE	    *pTail;		   /* 最后1個節(jié)點的指針 */
    SINGLENODE      *pCur;         /* 當前節(jié)點的指針 */
	UINT             uCount;       /* 保存鏈表節(jié)點的個數(shù) */
} SINGLELIST, *PSINGLELIST;


/* 鏈表的枚舉數(shù)據(jù)結(jié)構(gòu) */
typedef struct SINGLELIST_ENUM_st {
    SINGLENODE  *pCur;         /* 當前枚舉的節(jié)點指針 */
    COMPAREFUNC  CompareFunc;  /* 節(jié)點數(shù)據(jù)比較函數(shù) */
    void        *pMatchData;   /* 要枚舉的匹配數(shù)據(jù) */
} SINGLELIST_ENUM;


/**	單向鏈表的創(chuàng)建函數(shù)，創(chuàng)建完后鏈表還是空的沒有節(jié)點在里面

	@param	void - 無	
	@return	SINGLELIST * - 失敗返回NULL, 成功時返回一個單向鏈表結(jié)構(gòu)體指針	
*/
SINGLELIST * SingleList_Create( void );

/**	單向鏈表的釋放函數(shù)

	@param	SINGLELIST *pSingleList - 要釋放的單向鏈表的指針	
	@param	DESTROYFUNC pDestroyFunc - 鏈表節(jié)點數(shù)據(jù)釋放回調(diào)函數(shù)	
	@return	void - 無	
*/
void SingleList_Destroy( SINGLELIST *pSingleList, DESTROYFUNC DestroyFunc );

/**	單向鏈表的添加節(jié)點函數(shù)，添加的節(jié)點放在單向鏈表的頭部

	@param	SINGLELIST *pSingleList - 要添加的單向鏈表指針	
	@param	void *pData - 要添加的節(jié)點的數(shù)據(jù)指針	
	@return	INT - 失敗返回0，成功返回1	
*/
INT	SingleList_InsertHead( SINGLELIST *pSingleList, void *pData );

/**	單向鏈表的添加節(jié)點函數(shù)，添加的節(jié)點放在單向鏈表的尾部

	@param	SINGLELIST *pSingleList - 要添加的單向鏈表指針	
	@param	void *pData - 要添加的節(jié)點的數(shù)據(jù)指針
	@return	INT - 失敗返回0，成功返回1	
*/
INT	SingleList_InsertTail( SINGLELIST *pSingleList, void *pData );

/**	單向鏈表的彈出頭節(jié)點函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@return	void * - 失敗返回NULL, 成功返回要彈出的頭節(jié)點的數(shù)據(jù)指針	
*/
void *	SingleList_PopHead( SINGLELIST *pSingleList );

/**	單向鏈表的彈出尾節(jié)點函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@return	void * -  失敗返回NULL, 成功返回要彈出的尾節(jié)點的數(shù)據(jù)指針	
*/
void *	SingleList_PopTail( SINGLELIST *pSingleList );

/**	鏈表的刪除節(jié)點函數(shù)，它將刪除和pMatchData參數(shù)有相同數(shù)據(jù)的節(jié)點
    如果有許多有相同數(shù)據(jù)的節(jié)點它將只刪除第一個有相同數(shù)據(jù)的節(jié)點

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@param	void *pMatchData - 要刪除節(jié)點的匹配數(shù)據(jù)	
	@param	COMPAREFUNC CompareFunc - 數(shù)據(jù)比較函數(shù)用來比較pMatchData參數(shù)和鏈表
                                      節(jié)點參數(shù)是否相等	
	@param	DESTROYFUNC DestroyFunc - 鏈表節(jié)點的數(shù)據(jù)釋放函數(shù)	
	@return	INT (by default) - 0表示失敗或鏈表中沒有匹配的數(shù)據(jù)，1表示成功刪除	
*/
INT		SingleList_Delete( SINGLELIST *pSingleList,  
                        void *pMatchData, 
                        COMPAREFUNC CompareFunc, 
                        DESTROYFUNC DestroyFunc );

/**	單向鏈表的獲取指定位置數(shù)據(jù)的函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@param	UINT uIndex - 要獲取的索引位置	
	@return	void * - 索引位置節(jié)點的數(shù)據(jù)指針	
*/
void *  SingleList_GetAt( SINGLELIST *pSingleList, UINT uIndex );

/**	單向鏈表的獲取鏈表節(jié)點數(shù)量函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@return	UINT - 鏈表節(jié)點數(shù)量，為0表示鏈表是空的沒有節(jié)點在鏈表里面	
*/
UINT    SingleList_GetCount(SINGLELIST *pSingleList);

/**	單向鏈表的獲取頭節(jié)點函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@return	void * - 頭節(jié)點的數(shù)據(jù)指針	
*/
void *	SingleList_GetHead( SINGLELIST *pSingleList );

/**	單向鏈表的獲取當前節(jié)點函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針 	
	@return	void * - 當前節(jié)點的數(shù)據(jù)指針	
*/
void *	SingleList_GetCursor( SINGLELIST *pSingleList );

/**	單向鏈表的獲取尾節(jié)點函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@return	void * - 尾節(jié)點的數(shù)據(jù)指針	
*/
void * 	SingleList_GetTail( SINGLELIST *pSingleList );


/**	單向鏈表的枚舉函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針
	@return	void  - 無
*/
void SingleList_EnumBegin( SINGLELIST *pSingleList );

/**	單向鏈表枚舉下一個節(jié)點的函數(shù)，
    第一次調(diào)用此函數(shù)前必須先調(diào)用SingleList_EnumBegin()函數(shù)

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表的指針	
	@return	void * - 枚舉到的節(jié)點數(shù)據(jù)指針	
*/
void *  SingleList_EnumNext( SINGLELIST *pSingleList );


/**	單向鏈表的遍歷函數(shù)

	@param	SINGLELIST *pSingleList - 要操作單向鏈表指針	
	@param	TRAVERSEFUNC TraverseFunc - 節(jié)點數(shù)據(jù)的遍歷操作函數(shù)	
	@return	INT - 成功返回1，失敗返回0	
*/
INT SingleList_Traverse( SINGLELIST *pSingleList, TRAVERSEFUNC TraverseFunc );

/**	單向鏈表的插入排序函數(shù)
    排序是按照從小到大進行排列，這里說的大小是由CompareFunc來決定的
    因此用戶可以通過CompareFunc的返回值設置來決定使用順序排序或逆序排序

	@param	SINGLELIST *pSingleList - 要操作的單向鏈表指針	
	@param	COMPAREFUNC CompareFunc - 節(jié)點數(shù)據(jù)比較函數(shù)	
	@return	INT - 成功返回1，失敗返回0	
*/
INT SingleList_InsertSort( SINGLELIST *pSingleList, COMPAREFUNC CompareFunc );

SINGLELIST * SingleList_Split(SINGLELIST *pSingleList, UINT uCount);

INT SingleList_Merge( SINGLELIST *pSingleListA, 
                      SINGLELIST *pSingleListB, 
                      COMPAREFUNC CompareFunc );

INT SingleList_MergeSort( SINGLELIST *pSingleList, 
                          COMPAREFUNC CompareFunc, 
                          UINT uInsertSortCount );

INT SingleList_RadixSort( SINGLELIST *pSingleList,
                          UINT uRadix,
                          UINT uMaxKeyLen,
                          GETKEYFUNC GetKeyFunc );

UINT GetStrKeyNoCase( void *pszData, UINT uKeyIndex );
UINT GetStrKey( void *pszData, UINT uKeyIndex );
UINT GetIntKey( void *pData, UINT uKeyIndex );


#ifdef __cplusplus
}
#endif


#endif /* __SINGLELIST_H__ */