Woolz Image Processing  Version 1.7.5
libhguDlpList

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_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

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

HGUDlpListHGUDlpListDup (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...

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

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

HGUDlpListItemHGUDlpListExchange (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...

HGUDlpListItemHGUDlpListDeleteAll (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...

HGUDlpListItemHGUDlpListDelete (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...

HGUDlpListItemHGUDlpListRemove (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...

HGUDlpListItemHGUDlpListIterate (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...

HGUDlpListItemHGUDlpListNth (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...

HGUDlpListItemHGUDlpListTail (HGUDlpList *list)
Returns the tail list item. More...

Returns the head list item. More...

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

HGUDlpListItemHGUDlpListPrev (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_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.

 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().

 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.

 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
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.