Woolz Image Processing  Version 1.7.0
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_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

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...
 
HGUDlpListItemHGUDlpListHead (HGUDlpList *list)
 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

List traversal direction; Typedef: HGUDlpListDirection.

Enumerator
HGU_DLPLIST_DIR_TOHEAD 
HGU_DLPLIST_DIR_TOTAIL 

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
lockFnThe 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
listThe 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
listThe list data structure.
insBeforeGiven item that entry is to be inserted before, if NULL then the item is inserted at the head of the list.
entryNew list entry.
freeFnFunction 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
listThe list data structure.
appAfterGiven item that entry is to be inserted after, if NULL then the item is appended at the tail of the list.
entryNew list entry.
freeFnFunction 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
listThe list data structure.
item0First item (maybe before, after or even the same as the second item.
item1The 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
listThe 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
listThe list data structure.
itemItem 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
listThe list data structure.
itemItem 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
listThe list data structure.
entryCompFnGiven 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
listThe list data structure.
itemFirst 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).
dirIteration direction, either towards the head or the tail.
iterFnFunction to be iterated, see example above.
iterDataData 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
listThe list data structure.
itemGiven item from which to find the n'th item.
dirThe direction from given item, either towards the head or the tail.
offsetThe 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
listThe list data structure.
itemGiven item from which to find the offset to the head or the tail.
dirThe 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
listThe list data structure.
itemIs 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
listThe list data structure.
itemIs 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
listThe list data structure.
itemItem 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
listThe list data structure.
itemItem for which to change entry.
newEntryNew 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
listThe 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
listThe 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
listThe list data structure.
itemItem 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
listThe list data structure.
itemItem 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
listThe list data structure.

References HGU_DLPLIST_STATE_LOCK, and HGU_DLPLIST_STATE_UNLOCK.