Index: /trunk/psLib/src/collections/psList.h =================================================================== --- /trunk/psLib/src/collections/psList.h (revision 1473) +++ /trunk/psLib/src/collections/psList.h (revision 1474) @@ -10,6 +10,6 @@ * @ingroup LinkedList * - * @version $Revision: 1.13 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:55 $ + * @version $Revision: 1.14 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-11 20:04:51 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -33,10 +33,10 @@ */ enum { - PS_LIST_HEAD = 0, ///< at head - PS_LIST_TAIL = -1, ///< at tail - PS_LIST_PREVIOUS = -2, ///< previous element - PS_LIST_CURRENT = -3, ///< current element - PS_LIST_NEXT = -4, ///< next element - PS_LIST_UNKNOWN = -5 ///< unknown position (should be last in enum list) + PS_LIST_HEAD = 0, ///< at head + PS_LIST_TAIL = -1, ///< at tail + PS_LIST_PREVIOUS = -2, ///< previous element + PS_LIST_CURRENT = -3, ///< current element + PS_LIST_NEXT = -4, ///< next element + PS_LIST_UNKNOWN = -5 ///< unknown position (should be last in enum list) }; @@ -44,7 +44,7 @@ typedef struct psListElem { - struct psListElem* prev; ///< previous link in list - struct psListElem* next; ///< next link in list - void *data; ///< real data item + struct psListElem* prev; ///< previous link in list + struct psListElem* next; ///< next link in list + void *data; ///< real data item } psListElem; @@ -57,10 +57,10 @@ typedef struct { - unsigned int size; ///< number of elements on list - psListElem* head; ///< first element on list (may be NULL) - psListElem* tail; ///< last element on list (may be NULL) - psListElem* iter; ///< iteration cursor - unsigned int iterIndex; ///< the numeric position of the iteration cursor in the list - pthread_mutex_t lock; ///< mutex to lock a node during changes + unsigned int size; ///< number of elements on list + psListElem* head; ///< first element on list (may be NULL) + psListElem* tail; ///< last element on list (may be NULL) + psListElem* iter; ///< iteration cursor + unsigned int iterIndex; ///< the numeric position of the iteration cursor in the list + pthread_mutex_t lock; ///< mutex to lock a node during changes } psList; @@ -70,7 +70,8 @@ * @return psList* A new psList object. */ -psList* psListAlloc(void *data - ///< initial data item; may be NULL if no an empty psList is desired - ) +psList* psListAlloc( + void *data + ///< initial data item; may be NULL if no an empty psList is desired +) ; @@ -80,8 +81,9 @@ * NULL, the return value will also be NULL. */ -bool psListAdd(psList* restrict list, ///< list to add to (if NULL, nothing is done) - void *data, ///< data item to add. If NULL, list is not modified. - int where ///< index, PS_LIST_HEAD, PS_LIST_TAIL, or numbered location. - ); +bool psListAdd( + psList* restrict list, ///< list to add to (if NULL, nothing is done) + void *data, ///< data item to add. If NULL, list is not modified. + int where ///< index, PS_LIST_HEAD, PS_LIST_TAIL, or numbered location. +); /** Remove an item from a list. If which parameter is PS_LIST_UNKNOWN, @@ -89,11 +91,12 @@ * @return bool TRUE if element is successfully removed, otherwise FALSE. */ -bool psListRemove(psList* restrict list, - ///< list to remove element from - void *data, - ///< if which is PS_LIST_UNKNOWN, data item to find and remove, otherwise this is ignored. - int which - ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV, or numbered location. - ); +bool psListRemove( + psList* restrict list, + ///< list to remove element from + void *data, + ///< if which is PS_LIST_UNKNOWN, data item to find and remove, otherwise this is ignored. + int which + ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV, or numbered location. +); /** Retrieve an item from a list. @@ -104,7 +107,8 @@ * NULL is returned. */ -void *psListGet(psList* restrict list, ///< list to retrieve element from - int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN - ); +void *psListGet( + psList* restrict list, ///< list to retrieve element from + int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN +); /** Set the iterator of the list to a given position. If where is invalid the @@ -112,7 +116,8 @@ * */ -void psListSetIterator(psList* restrict list, ///< list to retrieve element from - int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL - ); +void psListSetIterator( + psList* restrict list, ///< list to retrieve element from + int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL +); /** Get next element relative to the iterator. This also moves the iterator to @@ -123,6 +128,7 @@ * parameter was NULL. */ -void *psListGetNext(psList* restrict list ///< list to retrieve element from - ); +void *psListGetNext( + psList* restrict list ///< list to retrieve element from +); /** Get current element according to the psList's iterator cursor. This does @@ -133,6 +139,7 @@ * iterator is not valid or list parameter was NULL. */ -void *psListGetCurrent(psList* restrict list ///< list to retrieve element from - ); +void *psListGetCurrent( + psList* restrict list ///< list to retrieve element from +); /** Get previous element relative to list's iterator. This also moves the @@ -143,6 +150,7 @@ * parameter was NULL. */ -void *psListGetPrevious(psList* restrict list ///< list to retrieve element from - ); +void *psListGetPrevious( + psList* restrict list ///< list to retrieve element from +); /** Convert a linked list to an array @@ -151,6 +159,7 @@ * or NULL if the given dlist parameter is NULL. */ -psArray* psListToArray(psList* dlist ///< List to convert - ); +psArray* psListToArray( + psList* dlist ///< List to convert +); /** Convert array to a doubly-linked list @@ -159,8 +168,23 @@ * or NULL is the given arr parameter is NULL. */ -psList* psArrayToList(psArray* arr ///< vector to convert - ); +psList* psArrayToList( + psArray* arr ///< vector to convert +); -psList* psListSort(psList* list, psComparePtrFcn compare); +/** Sort a list via a comparison function. + * + * The comparison function must return an integer less than, equal to, or + * greater than zero if the first argument is considered to be respectively + * less than, equal to, or greater than the second. + * + * If two members compare as equal, their order in the sorted array is + * undefined. + * + * @return psList* Sorted list. + */ +psList* psListSort( + psList* list, ///< the list to sort + psComparePtrFcn compare ///< the comparison function +); /// @} End of DataGroup Functions Index: /trunk/psLib/src/types/psList.h =================================================================== --- /trunk/psLib/src/types/psList.h (revision 1473) +++ /trunk/psLib/src/types/psList.h (revision 1474) @@ -10,6 +10,6 @@ * @ingroup LinkedList * - * @version $Revision: 1.13 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:55 $ + * @version $Revision: 1.14 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-11 20:04:51 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -33,10 +33,10 @@ */ enum { - PS_LIST_HEAD = 0, ///< at head - PS_LIST_TAIL = -1, ///< at tail - PS_LIST_PREVIOUS = -2, ///< previous element - PS_LIST_CURRENT = -3, ///< current element - PS_LIST_NEXT = -4, ///< next element - PS_LIST_UNKNOWN = -5 ///< unknown position (should be last in enum list) + PS_LIST_HEAD = 0, ///< at head + PS_LIST_TAIL = -1, ///< at tail + PS_LIST_PREVIOUS = -2, ///< previous element + PS_LIST_CURRENT = -3, ///< current element + PS_LIST_NEXT = -4, ///< next element + PS_LIST_UNKNOWN = -5 ///< unknown position (should be last in enum list) }; @@ -44,7 +44,7 @@ typedef struct psListElem { - struct psListElem* prev; ///< previous link in list - struct psListElem* next; ///< next link in list - void *data; ///< real data item + struct psListElem* prev; ///< previous link in list + struct psListElem* next; ///< next link in list + void *data; ///< real data item } psListElem; @@ -57,10 +57,10 @@ typedef struct { - unsigned int size; ///< number of elements on list - psListElem* head; ///< first element on list (may be NULL) - psListElem* tail; ///< last element on list (may be NULL) - psListElem* iter; ///< iteration cursor - unsigned int iterIndex; ///< the numeric position of the iteration cursor in the list - pthread_mutex_t lock; ///< mutex to lock a node during changes + unsigned int size; ///< number of elements on list + psListElem* head; ///< first element on list (may be NULL) + psListElem* tail; ///< last element on list (may be NULL) + psListElem* iter; ///< iteration cursor + unsigned int iterIndex; ///< the numeric position of the iteration cursor in the list + pthread_mutex_t lock; ///< mutex to lock a node during changes } psList; @@ -70,7 +70,8 @@ * @return psList* A new psList object. */ -psList* psListAlloc(void *data - ///< initial data item; may be NULL if no an empty psList is desired - ) +psList* psListAlloc( + void *data + ///< initial data item; may be NULL if no an empty psList is desired +) ; @@ -80,8 +81,9 @@ * NULL, the return value will also be NULL. */ -bool psListAdd(psList* restrict list, ///< list to add to (if NULL, nothing is done) - void *data, ///< data item to add. If NULL, list is not modified. - int where ///< index, PS_LIST_HEAD, PS_LIST_TAIL, or numbered location. - ); +bool psListAdd( + psList* restrict list, ///< list to add to (if NULL, nothing is done) + void *data, ///< data item to add. If NULL, list is not modified. + int where ///< index, PS_LIST_HEAD, PS_LIST_TAIL, or numbered location. +); /** Remove an item from a list. If which parameter is PS_LIST_UNKNOWN, @@ -89,11 +91,12 @@ * @return bool TRUE if element is successfully removed, otherwise FALSE. */ -bool psListRemove(psList* restrict list, - ///< list to remove element from - void *data, - ///< if which is PS_LIST_UNKNOWN, data item to find and remove, otherwise this is ignored. - int which - ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV, or numbered location. - ); +bool psListRemove( + psList* restrict list, + ///< list to remove element from + void *data, + ///< if which is PS_LIST_UNKNOWN, data item to find and remove, otherwise this is ignored. + int which + ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV, or numbered location. +); /** Retrieve an item from a list. @@ -104,7 +107,8 @@ * NULL is returned. */ -void *psListGet(psList* restrict list, ///< list to retrieve element from - int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN - ); +void *psListGet( + psList* restrict list, ///< list to retrieve element from + int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN +); /** Set the iterator of the list to a given position. If where is invalid the @@ -112,7 +116,8 @@ * */ -void psListSetIterator(psList* restrict list, ///< list to retrieve element from - int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL - ); +void psListSetIterator( + psList* restrict list, ///< list to retrieve element from + int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL +); /** Get next element relative to the iterator. This also moves the iterator to @@ -123,6 +128,7 @@ * parameter was NULL. */ -void *psListGetNext(psList* restrict list ///< list to retrieve element from - ); +void *psListGetNext( + psList* restrict list ///< list to retrieve element from +); /** Get current element according to the psList's iterator cursor. This does @@ -133,6 +139,7 @@ * iterator is not valid or list parameter was NULL. */ -void *psListGetCurrent(psList* restrict list ///< list to retrieve element from - ); +void *psListGetCurrent( + psList* restrict list ///< list to retrieve element from +); /** Get previous element relative to list's iterator. This also moves the @@ -143,6 +150,7 @@ * parameter was NULL. */ -void *psListGetPrevious(psList* restrict list ///< list to retrieve element from - ); +void *psListGetPrevious( + psList* restrict list ///< list to retrieve element from +); /** Convert a linked list to an array @@ -151,6 +159,7 @@ * or NULL if the given dlist parameter is NULL. */ -psArray* psListToArray(psList* dlist ///< List to convert - ); +psArray* psListToArray( + psList* dlist ///< List to convert +); /** Convert array to a doubly-linked list @@ -159,8 +168,23 @@ * or NULL is the given arr parameter is NULL. */ -psList* psArrayToList(psArray* arr ///< vector to convert - ); +psList* psArrayToList( + psArray* arr ///< vector to convert +); -psList* psListSort(psList* list, psComparePtrFcn compare); +/** Sort a list via a comparison function. + * + * The comparison function must return an integer less than, equal to, or + * greater than zero if the first argument is considered to be respectively + * less than, equal to, or greater than the second. + * + * If two members compare as equal, their order in the sorted array is + * undefined. + * + * @return psList* Sorted list. + */ +psList* psListSort( + psList* list, ///< the list to sort + psComparePtrFcn compare ///< the comparison function +); /// @} End of DataGroup Functions