Convenience procedures for creating, managing and querying linked lists. libhguDlpList for more detail. More...

Files
file	HGUDlpList.c
	Data structures and functions for doubly linked lists of pointers.

file	HGUDlpList.h
	Data structures and functions for doubly linked lists linked lists of pointers.

Enumerations
enum	_HGUDlpListDirection { HGU_DLPLIST_DIR_TOHEAD, HGU_DLPLIST_DIR_TOTAIL }
	List traversal direction; Typedef: HGUDlpListDirection. More...

enum	_HGUDlpListState { HGU_DLPLIST_STATE_EMPTY = (0), HGU_DLPLIST_STATE_ERROR = (0), HGU_DLPLIST_STATE_UNLOCK = (1), HGU_DLPLIST_STATE_LOCK = (1<<1), HGU_DLPLIST_STATE_CREATE = (1<<2), HGU_DLPLIST_STATE_DESTROY = (1<<3) }
	State of list locking mechanism. Typedef: HGUDlpListState. More...

Functions
HGUDlpList *	HGUDlpListCreate (HGUDlpListState(lockFn)(void , HGUDlpListState))
	Creates a list data structure which is required by all the other HGUDlpList functions. More...

HGUDlpList *	HGUDlpListDup (HGUDlpList *givenList)
	Duplicates a list data structure, but NOT its items. Ie head and tail are both NULL and the item count is zero, only the lock function is common. More...

void	HGUDlpListDestroy (HGUDlpList *list)
	Destroys the given list list data structure and any list items. More...

HGUDlpListItem *	HGUDlpListInsert (HGUDlpList list, HGUDlpListItem insBefore, void entry, void(freeFn)(void *))
	Inserts the given entry into the list before the given item. More...

HGUDlpListItem *	HGUDlpListAppend (HGUDlpList list, HGUDlpListItem appAfter, void entry, void(freeFn)(void *))
	Appends the given entry into the list after the given item. More...

HGUDlpListItem *	HGUDlpListExchange (HGUDlpList list, HGUDlpListItem item0, HGUDlpListItem *item1)
	Exchanges the two given list item entries and not the items, so that head is still head and tail is still tail. More...

HGUDlpListItem *	HGUDlpListDeleteAll (HGUDlpList *list)
	Deletes all list items from the head on down to and including the tail. Where delete implies both the removal of items from the list and freeing the entries using the item's free functions (unless either the free function or the entry is NULL). More...

HGUDlpListItem *	HGUDlpListDelete (HGUDlpList list, HGUDlpListItem item)
	Deletes the given list item from the list with the given list. Where delete implies both the removal of an item, the freeing of the item AND (when neither the free function or the entry are NULL) it's entry too. More...

HGUDlpListItem *	HGUDlpListRemove (HGUDlpList list, HGUDlpListItem item)
	Removes the item from the list withe the given list. Where remove implies the removal of the item from the list and the freeing of the item EXCEPT for its entry. More...

int	HGUDlpListSort (HGUDlpList list, int(entryCompFn)(void , void ))
	Sorts the entire list using the given entry comparison function. More...

HGUDlpListItem *	HGUDlpListIterate (HGUDlpList list, HGUDlpListItem item, HGUDlpListDirection dir, int(iterFn)(HGUDlpList , HGUDlpListItem , void ), void *iterData)
	Iterates the given function through the list, starting with the supplied given item. The iteration may proceed toward either the head or tail of the list. The iterated function must take the form of: More...

HGUDlpListItem *	HGUDlpListNth (HGUDlpList list, HGUDlpListItem item, HGUDlpListDirection dir, int offset)
	Finds the n'th item from the given item in the list. The n'th item from the head or tail can be found by calling the function with item == NULL, in which case the direction of approach is optimised. More...

int	HGUDlpListOffset (HGUDlpList list, HGUDlpListItem item, HGUDlpListDirection dir)
	Counts the number of items from the given item to the item with a NULL next/prev item, which is at the head or tail of list. The offset between an item and itself is defined to be zero. More...

int	HGUDlpListItemIsHead (HGUDlpList list, HGUDlpListItem item)
	Looks to see if the given item is at the head of the given list. More...

int	HGUDlpListItemIsTail (HGUDlpList list, HGUDlpListItem item)
	Looks to see if the given item is at the tail of the given list. More...

void *	HGUDlpListEntryGet (HGUDlpList list, HGUDlpListItem item)
	Returns the list items entry. More...

void *	HGUDlpListEntrySet (HGUDlpList list, HGUDlpListItem item, void *newEntry)
	Sets the given items entry and returns the previous entry. Entries are NEVER freed by this function. More...

HGUDlpListItem *	HGUDlpListTail (HGUDlpList *list)
	Returns the tail list item. More...

HGUDlpListItem *	HGUDlpListHead (HGUDlpList *list)
	Returns the head list item. More...

HGUDlpListItem *	HGUDlpListNext (HGUDlpList list, HGUDlpListItem item)
	Returns the next list item. More...

HGUDlpListItem *	HGUDlpListPrev (HGUDlpList list, HGUDlpListItem item)
	Returns the prev list item. More...

int	HGUDlpListCount (HGUDlpList *list)
	Returns the number of items in the list. More...

Detailed Description

Convenience procedures for creating, managing and querying linked lists. libhguDlpList for more detail.

Enumeration Type Documentation

enum _HGUDlpListDirection

List traversal direction; Typedef: HGUDlpListDirection.

Enumerator
HGU_DLPLIST_DIR_TOHEAD
HGU_DLPLIST_DIR_TOTAIL

enum _HGUDlpListState

State of list locking mechanism. Typedef: HGUDlpListState.

Enumerator
HGU_DLPLIST_STATE_EMPTY
HGU_DLPLIST_STATE_ERROR
HGU_DLPLIST_STATE_UNLOCK
HGU_DLPLIST_STATE_LOCK
HGU_DLPLIST_STATE_CREATE
HGU_DLPLIST_STATE_DESTROY

Function Documentation

HGUDlpList* HGUDlpListCreate ( HGUDlpListState(*)(void *, HGUDlpListState) lockFn )

Creates a list data structure which is required by all the other HGUDlpList functions.

Returns: List data structure, or NULL on error.

Parameters

lockFn The lock function to be used when accessing the list. If NULL then no locking is used.

References HGU_DLPLIST_STATE_CREATE, and HGU_DLPLIST_STATE_LOCK.

Referenced by HGUDlpListDup().

HGUDlpList* HGUDlpListDup ( HGUDlpList * givenList )

Duplicates a list data structure, but NOT its items. Ie head and tail are both NULL and the item count is zero, only the lock function is common.

Returns: List data structure, or NULL on error.

Parameters

givenList

References HGUDlpListCreate().

void HGUDlpListDestroy ( HGUDlpList * list )

Destroys the given list list data structure and any list items.

Returns: void

Parameters

list	The list data structure.

References HGU_DLPLIST_STATE_DESTROY.

HGUDlpListItem* HGUDlpListInsert	(	HGUDlpList *	list,
		HGUDlpListItem *	insBefore,
		void *	entry,
		void()(void )	freeFn
	)

Inserts the given entry into the list before the given item.

Returns

Parameters

list	The list data structure.
insBefore	Given item that entry is to be inserted before, if NULL then the item is inserted at the head of the list.
entry	New list entry.
freeFn	Function that will be called (if not NULL) to free the entry should the item be deleted.

HGUDlpListItem* HGUDlpListAppend	(	HGUDlpList *	list,
		HGUDlpListItem *	appAfter,
		void *	entry,
		void()(void )	freeFn
	)

Appends the given entry into the list after the given item.

Returns: The appended list item, or NULL on error.

Parameters

list	The list data structure.
appAfter	Given item that entry is to be inserted after, if NULL then the item is appended at the tail of the list.
entry	New list entry.
freeFn	Function that will be called (if not NULL) to free the entry should the item be deleted.

HGUDlpListItem* HGUDlpListExchange	(	HGUDlpList *	list,
		HGUDlpListItem *	item0,
		HGUDlpListItem *	item1
	)

Exchanges the two given list item entries and not the items, so that head is still head and tail is still tail.

Returns: The first of the two list items (ie first in the parameter list) or NULL on error.

Parameters

list	The list data structure.
item0	First item (maybe before, after or even the same as the second item.
item1	The second item.

HGUDlpListItem* HGUDlpListDeleteAll ( HGUDlpList * list )

Deletes all list items from the head on down to and including the tail. Where delete implies both the removal of items from the list and freeing the entries using the item's free functions (unless either the free function or the entry is NULL).

Returns: New list head which is NULL if all the items were deleted ok.

Parameters

list	The list data structure.

HGUDlpListItem* HGUDlpListDelete	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Deletes the given list item from the list with the given list. Where delete implies both the removal of an item, the freeing of the item AND (when neither the free function or the entry are NULL) it's entry too.

Returns: Next list item after the item deleted, may be NULL either on error or if the list item was the last in the list.

Parameters

list	The list data structure.
item	Item to be deleted.

HGUDlpListItem* HGUDlpListRemove	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Removes the item from the list withe the given list. Where remove implies the removal of the item from the list and the freeing of the item EXCEPT for its entry.

Returns: Next list item after the item removed, may be NULL either on error or if the list item was the last in the list.

Parameters

list	The list data structure.
item	Item to be deleted.

int HGUDlpListSort	(	HGUDlpList *	list,
		int()(void , void *)	entryCompFn
	)

Sorts the entire list using the given entry comparison function.

Returns: Number of items in list or zero for an empty list or on error.

Parameters

list	The list data structure.
entryCompFn	Given entry comparison function which must return an integer less than, equal to, or greater than zero to indicate if the first entry is to be considered less than, equal to, or greater than the second.

HGUDlpListItem* HGUDlpListIterate	(	HGUDlpList *	list,
		HGUDlpListItem *	item,
		HGUDlpListDirection	dir,
		int()(HGUDlpList , HGUDlpListItem , void )	iterFn,
		void *	iterData
	)

Iterates the given function through the list, starting with the supplied given item. The iteration may proceed toward either the head or tail of the list. The iterated function must take the form of:

Returns: Last item to which the iterated function was applied, may be NULL on error.

                  int MyItemCount(HGUDlpList *list,
                                 HGUDlpListItem *item,
                                 void *myData)
                  {
                    int         *count;

                    if(list && item)
                    {
                      count = (int *)myData;
                      ++*count;
                    }
                    return(1);
                  }

Where the data parameter is the data supplied to this (HGUDlpListIterate) function. The iteration stops when: An error is encountered, either the head or tail list item has be processed, or when the supplied function returns zero. So the example function would count the number of items, from the given item to either the list head or tail.

Parameters

list	The list data structure.
item	First item of iteration which may be NULL to indicate list head (dir == HGU_DLPLIST_DIR_TO_TAIL) or tail (dir == HGU_DLPLIST_DIR_TO_HEAD).
dir	Iteration direction, either towards the head or the tail.
iterFn	Function to be iterated, see example above.
iterData	Data supplied to the iterated function.

References HGU_DLPLIST_DIR_TOHEAD, and HGU_DLPLIST_DIR_TOTAIL.

HGUDlpListItem* HGUDlpListNth	(	HGUDlpList *	list,
		HGUDlpListItem *	item,
		HGUDlpListDirection	dir,
		int	offset
	)

Finds the n'th item from the given item in the list. The n'th item from the head or tail can be found by calling the function with item == NULL, in which case the direction of approach is optimised.

Returns: Nth item from the given item, may be NULL on error or if the nth item is beyond the list head or tail.

Parameters

list	The list data structure.
item	Given item from which to find the n'th item.
dir	The direction from given item, either towards the head or the tail.
offset	The n in n'th. If zero then returns the given item, if the direction is towards the tail and offset == 1, then this is equivalent to HGUDlpListNext().

References HGU_DLPLIST_DIR_TOHEAD, and HGU_DLPLIST_DIR_TOTAIL.

int HGUDlpListOffset	(	HGUDlpList *	list,
		HGUDlpListItem *	item,
		HGUDlpListDirection	dir
	)

Counts the number of items from the given item to the item with a NULL next/prev item, which is at the head or tail of list. The offset between an item and itself is defined to be zero.

Returns: Number of items from the given item to the head or tail item of the list.

Parameters

list	The list data structure.
item	Given item from which to find the offset to the head or the tail.
dir	The direction from given item, either towards the head or the tail.

References HGU_DLPLIST_DIR_TOHEAD, and HGU_DLPLIST_DIR_TOTAIL.

int HGUDlpListItemIsHead	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Looks to see if the given item is at the head of the given list.

Returns: Non zero if the item is at the head of the list.

Parameters

list	The list data structure.
item	Is this item at the head of the list?

int HGUDlpListItemIsTail	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Looks to see if the given item is at the tail of the given list.

Returns: Non zero if the item is at the tail of the list.

Parameters

list	The list data structure.
item	Is this item at the tail of the list?

void* HGUDlpListEntryGet	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Returns the list items entry.

Returns: The list item's entry, which may be NULL for an empty list or on error.

Parameters

list	The list data structure.
item	Item with the entry.

void* HGUDlpListEntrySet	(	HGUDlpList *	list,
		HGUDlpListItem *	item,
		void *	newEntry
	)

Sets the given items entry and returns the previous entry. Entries are NEVER freed by this function.

Returns: The previous entry.

Parameters

list	The list data structure.
item	Item for which to change entry.
newEntry	New entry to be interted into the given item.

HGUDlpListItem* HGUDlpListTail ( HGUDlpList * list )

Returns the tail list item.

Returns: List item at tail of list, may may be NULL either on error or if the list is empty.

Parameters

list	The list data structure.

HGUDlpListItem* HGUDlpListHead ( HGUDlpList * list )

Returns the head list item.

Returns: List item at head of list, may may be NULL either on error or if the list is empty.

Parameters

list	The list data structure.

HGUDlpListItem* HGUDlpListNext	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Returns the next list item.

Returns: Next list item after the given item, may be NULL on error, if the list is empty or if the given item was at the tail of the list.

Parameters

list	The list data structure.
item	Item with the entry.

References _BibFileField::next.

HGUDlpListItem* HGUDlpListPrev	(	HGUDlpList *	list,
		HGUDlpListItem *	item
	)

Returns the prev list item.

Returns: Prev list item before the given item, may be NULL on error, if the list is empty or if the given item was at the head of the list.

Parameters

list	The list data structure.
item	Item with the entry.

int HGUDlpListCount ( HGUDlpList * list )

Returns the number of items in the list.

Returns: Number of items in list. This is >= zero for a valid list but may be negative if the list is invalid.

Parameters

list	The list data structure.

References HGU_DLPLIST_STATE_LOCK, and HGU_DLPLIST_STATE_UNLOCK.

Files

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation