A doubly-linked list library. More...

#include "libComAPI.h"

Include dependency graph for ellLib.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	ELLNODE
	List node type. More...

struct	ELLLIST
	List header type. More...

Macros
#define	ELLNODE_INIT {NULL, NULL}
	Value of a terminal node.

#define	ELLLIST_INIT {ELLNODE_INIT, 0}
	Value of an empty list.

#define	ellInit(PLIST)
	Initialize a list type. More...

#define	ellCount(PLIST) ((PLIST)->count)
	Report the number of nodes in a list. More...

#define	ellFirst(PLIST) ((PLIST)->node.next)
	Find the first node in list. More...

#define	ellLast(PLIST) ((PLIST)->node.previous)
	Find the last node in list. More...

#define	ellNext(PNODE) ((PNODE)->next)
	Find the next node in list. More...

#define	ellPrevious(PNODE) ((PNODE)->previous)
	Find the previous node in list. More...

#define	ellFree(PLIST) ellFree2(PLIST, free)
	Free up the list. More...

Typedefs
typedef void(*	FREEFUNC) (void *)
	Pointer to free() for use by ellFree() macro. More...

typedef int(*	pListCmp) (const ELLNODE A, const ELLNODE B)

Functions
LIBCOM_API void	ellAdd (ELLLIST pList, ELLNODE pNode)
	Adds a node to the end of a list. More...

LIBCOM_API void	ellConcat (ELLLIST pDstList, ELLLIST pAddList)
	Concatenates a list to the end of another list. The list to be added is left empty. Either list (or both) can be empty at the beginning of the operation. More...

LIBCOM_API void	ellDelete (ELLLIST pList, ELLNODE pNode)
	Deletes a node from a list. More...

LIBCOM_API void	ellExtract (ELLLIST pSrcList, ELLNODE pStartNode, ELLNODE pEndNode, ELLLIST pDstList)
	Extract a sublist from a list. More...

LIBCOM_API ELLNODE *	ellGet (ELLLIST *pList)
	Deletes and returns the first node from a list. More...

LIBCOM_API ELLNODE *	ellPop (ELLLIST *pList)
	Deletes and returns the last node from a list. More...

LIBCOM_API void	ellInsert (ELLLIST plist, ELLNODE pPrev, ELLNODE *pNode)
	Inserts a node into a list immediately after a specific node. More...

LIBCOM_API ELLNODE *	ellNth (ELLLIST *pList, int nodeNum)
	Find the Nth node in a list. More...

LIBCOM_API ELLNODE *	ellNStep (ELLNODE *pNode, int nStep)
	Find the list node `nStep` steps away from a specified node. More...

LIBCOM_API int	ellFind (ELLLIST pList, ELLNODE pNode)
	Find the index of a specific node in a list. More...

LIBCOM_API void	ellSortStable (ELLLIST *pList, pListCmp pListCmp)
	Stable (MergeSort) of a given list. More...

LIBCOM_API void	ellFree2 (ELLLIST *pList, FREEFUNC freeFunc)
	Free all the nodes in a list. More...

LIBCOM_API void	ellVerify (ELLLIST *pList)
	Verifies that the list is consistent. More...

Detailed Description

Author: John Winans (ANL); Andrew Johnson (ANL)

This provides similar functionality to the VxWorks lstLib library.

Supports the creation and maintenance of a doubly-linked list. The user supplies a list descriptor (type ELLLIST) that will contain pointers to the first and last nodes in the list, and a count of the number of nodes in the list. The nodes in the list can be any user-defined structure, but they must reserve space for two pointers as their first elements. Both the forward and backward chains are terminated with a NULL pointer.

Definition in file ellLib.h.

Macro Definition Documentation

◆ ellInit

#define ellInit ( PLIST )

Value:

{\
    (PLIST)->node.next = (PLIST)->node.previous = NULL;\
    (PLIST)->count = 0;\
}

Parameters

PLIST Pointer to list header to be initialized

Definition at line 77 of file ellLib.h.

◆ ellCount

#define ellCount ( PLIST ) ((PLIST)->count)

Parameters

PLIST Pointer to list descriptor

Returns: Number of nodes in the list

Definition at line 85 of file ellLib.h.

◆ ellFirst

#define ellFirst ( PLIST ) ((PLIST)->node.next)

Parameters

PLIST Pointer to list descriptor

Returns: Pointer to first node in the list

Definition at line 90 of file ellLib.h.

◆ ellLast

#define ellLast ( PLIST ) ((PLIST)->node.previous)

Parameters

PLIST Pointer to list descriptor

Returns: Pointer to last node in the list

Definition at line 95 of file ellLib.h.

◆ ellNext

#define ellNext ( PNODE ) ((PNODE)->next)

Parameters

PNODE Pointer to node whose successor is to be found

Returns: Pointer to the node following PNODE

Definition at line 100 of file ellLib.h.

◆ ellPrevious

#define ellPrevious ( PNODE ) ((PNODE)->previous)

Parameters

PNODE Pointer to node whose predecessor is to be found

Returns: Pointer to the node prior to PNODE

Definition at line 105 of file ellLib.h.

◆ ellFree

#define ellFree ( PLIST ) ellFree2(PLIST, free)

Parameters

PLIST List for which to free all nodes

Definition at line 109 of file ellLib.h.

Typedef Documentation

◆ FREEFUNC

typedef void(* FREEFUNC) (void *)

This is required for use on Windows, where each DLL has its own free() function. The ellFree() macro passes the application's version of free() to the ellFree2() function.

Definition at line 72 of file ellLib.h.

Function Documentation

◆ ellAdd()

LIBCOM_API void ellAdd	(	ELLLIST *	pList,
		ELLNODE *	pNode
	)

Parameters

pList	Pointer to list descriptor
pNode	Pointer to node to be added

◆ ellConcat()

LIBCOM_API void ellConcat	(	ELLLIST *	pDstList,
		ELLLIST *	pAddList
	)

Parameters

pDstList	Destination list
pAddList	List to be added to `pDstList`

◆ ellDelete()

LIBCOM_API void ellDelete	(	ELLLIST *	pList,
		ELLNODE *	pNode
	)

Parameters

pList	Pointer to list descriptor
pNode	Pointer to node to be deleted

◆ ellExtract()

LIBCOM_API void ellExtract	(	ELLLIST *	pSrcList,
		ELLNODE *	pStartNode,
		ELLNODE *	pEndNode,
		ELLLIST *	pDstList
	)

Parameters

pSrcList	Pointer to source list
pStartNode	First node in `pSrcList` to be extracted
pEndNode	Last node in `pSrcList` to be extracted
pDstList	Pointer to list where to put extracted list

◆ ellGet()

LIBCOM_API ELLNODE* ellGet ( ELLLIST * pList )

Parameters

pList Pointer to list from which to get node

Returns: Pointer to the first node from the list, or NULL if the list is empty

◆ ellPop()

LIBCOM_API ELLNODE* ellPop ( ELLLIST * pList )

Parameters

pList Pointer to list from which to get node

Returns: Pointer to the last node from the list, or NULL if the list is empty

◆ ellInsert()

LIBCOM_API void ellInsert	(	ELLLIST *	plist,
		ELLNODE *	pPrev,
		ELLNODE *	pNode
	)

Parameters

plist	Pointer to list into which to insert node
pPrev	Pointer to the node after which to insert
pNode	Pointer to the node to be inserted

Note: If pPrev is NULL pNode will be inserted at the head of the list

◆ ellNth()

LIBCOM_API ELLNODE* ellNth	(	ELLLIST *	pList,
		int	nodeNum
	)

Parameters

pList	Pointer to list from which to find node
nodeNum	Index of the node to be found

Returns: Pointer to the element at index nodeNum in pList, or NULL if there is no such node in the list.

Note: The first node has index 1.

◆ ellNStep()

LIBCOM_API ELLNODE* ellNStep	(	ELLNODE *	pNode,
		int	nStep
	)

Parameters

pNode	The known node
nStep	How many steps to take, may be negative to step backwards

Returns: Pointer to the node nStep nodes from pNode, or NULL if there is no such node in the list.

◆ ellFind()

LIBCOM_API int ellFind	(	ELLLIST *	pList,
		ELLNODE *	pNode
	)

Parameters

pList	Pointer to list to search
pNode	Pointer to node to search for

Returns: The node's index, or -1 if it cannot be found on the list.

Note: The first node has index 1.

◆ ellSortStable()

LIBCOM_API void ellSortStable	(	ELLLIST *	pList,
		pListCmp	pListCmp
	)

Parameters

pList	Pointer to list to be sorted
pListCmp	Compare function to be used

Note: The comparison function cmp(A,B) is expected to return -1 for A<B, 0 for A==B, and 1 for A>B.; Use of mergesort algorithm based on analysis by http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html

◆ ellFree2()

LIBCOM_API void ellFree2	(	ELLLIST *	pList,
		FREEFUNC	freeFunc
	)

This routine empties a list, calling freeFunc() for every node on it.

Parameters

pList	List from which to free all nodes
freeFunc	The free() routine to be called

Note: The nodes in the list are free()'d on the assumption that the node structures were malloc()'d one-at-a-time and that the ELLNODE structure is the first member of the parent structure.

◆ ellVerify()

LIBCOM_API void ellVerify ( ELLLIST * pList )

Parameters

pList List to be verified

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ellInit

◆ ellCount

◆ ellFirst

◆ ellLast

◆ ellNext

◆ ellPrevious

◆ ellFree

Typedef Documentation

◆ FREEFUNC

Function Documentation

◆ ellAdd()

◆ ellConcat()

◆ ellDelete()

◆ ellExtract()

◆ ellGet()

◆ ellPop()

◆ ellInsert()

◆ ellNth()

◆ ellNStep()

◆ ellFind()

◆ ellSortStable()

◆ ellFree2()

◆ ellVerify()