Index: /trunk/psLib/src/collections/psList.c =================================================================== --- /trunk/psLib/src/collections/psList.c (revision 1016) +++ /trunk/psLib/src/collections/psList.c (revision 1017) @@ -6,6 +6,6 @@ * @author Robert Daniel DeSonia, MHPCC * - * @version $Revision: 1.4 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-06-09 19:50:32 $ + * @version $Revision: 1.5 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-06-12 22:15:39 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii Index: /trunk/psLib/src/collections/psList.h =================================================================== --- /trunk/psLib/src/collections/psList.h (revision 1016) +++ /trunk/psLib/src/collections/psList.h (revision 1017) @@ -10,6 +10,6 @@ * @ingroup LinkedList * - * @version $Revision: 1.3 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-06-10 01:58:06 $ + * @version $Revision: 1.4 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-06-12 22:15:39 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -42,17 +42,21 @@ typedef struct psListElem { - struct psListElem *prev; ///< previous link in list - struct psListElem *next; ///< next link in list + struct psListElem *prev; ///< previous link in list + struct psListElem *next; ///< next link in list void *data; ///< real data item } psListElem; -/** Doubly-linked list */ +/** The psList Linked list structure. User should not allocate this struct + * directly; rather the psListAlloc should be used. + * + * @see psListAlloc, psListFree + */ 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 + 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 @@ -60,72 +64,130 @@ psList; -/** Constructor */ -psList *psListAlloc( - void *data ///< initial data item; may be NULL +/** Creates a psList linked list object. + * + * @return psList* A new psList object. + */ +psList* psListAlloc( + void *data + ///< initial data item; may be NULL if no an empty psList is desired ) ; #include "psMemory.h" -/** Destructor */ +/** Destroys a psList linked list object. This also frees the elements of the + * list using the psFreeFcn given, if any. If no psFreeFcn is specified, + * the elements are just dereferenced via psMemDecrRefCounter(...). + * + */ void psListFree( - psList* restrict list, ///< list to destroy + psList* restrict list, ///< list to destroy psFreeFcn elemFree ///< destructor for data on list ); -/** Add to list */ +/** Adds an element to a psList at position given. + * + * @return psList* The psList with added data item. If list parameter is + * NULL, the return value will also be NULL. + */ psList* psListAdd( - psList* restrict list, ///< list to add to (may be NULL) - void* data, ///< data item to add - int where ///< index, PS_LIST_HEAD, or PS_LIST_TAIL + 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. ); -/** Append to a list */ +/** Appends an item to a psList. + * + * @return psList* The psList with added data item. If list parameter is + * NULL, the return value will also be NULL. + */ psList* psListAppend( - psList* restrict list, ///< list to append to (may be NULL) - void *data ///< data item to add + psList* restrict list, ///< list to append to (if NULL, nothing is done) + void *data ///< data item to add. If NULL, list is not modified. ); -/** Remove from a list */ +/** Remove an item from a list. If which parameter is PS_LIST_UNKNOWN, + * + * @return void* The data item that was removed. If NULL, no item was + * removed. + */ void* psListRemove( - psList* restrict list, ///< list to remove element from - void *data, ///< data item to remove - int which ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV + 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 from a list */ +/** Retrieve an item from a list. + * + * @return void* the item corresponding to the which parameter. If + * which is invalid (e.g., a numbered index greater + * than the list size or if the list is empty), a + * NULL is returned. + */ void* psListGet( psList* restrict list, ///< list to retrieve element from - int which ///< index of item, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN + int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN ); -/** Set the iterator */ +/** Set the iterator of the list to a given position. If where is invalid the + * iterator position is not changed. + * + */ void psListSetIterator( psList* restrict list, ///< list to retrieve element from - int where ///< index, PS_LIST_HEAD, or PS_LIST_TAIL + int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL ); -/** Get next element relative to iter */ +/** Get next element relative to the iterator. This also moves the iterator to + * the next list position. + * + * @return void* the data item next on the list or NULL if the iterator + * is already pointing to the last element or the list + * parameter was NULL. + */ void* psListGetNext( psList* restrict list ///< list to retrieve element from ); -/** Get current element at iter */ +/** Get current element according to the psList's iterator cursor. This does + * not move the iterator location. + * + * @return void* the data item cooresponding to current iterator + * cursor position of the list, or NULL if either the + * iterator is not valid or list parameter was NULL. + */ void* psListGetCurrent( psList* restrict list ///< list to retrieve element from ); -/** Get prev element relative to iter */ +/** Get previous element relative to list's iterator. This also moves the + * iterator to the previous list position. + * + * @return void* the data item previous on the list or NULL if the iterator + * is already pointing to the first element or the list + * parameter was NULL. + */ void* psListGetPrevious( psList* restrict list ///< list to retrieve element from ); -/** Convert doubly-linked list to an array */ +/** Convert a linked list to an array + * + * @return psVector* A new psVector populated with elements from the list, + * or NULL if the given dlist parameter is NULL. + */ psVector* psListToVector( psList *dlist ///< List to convert ); -/** Convert array to a doubly-linked list */ +/** Convert array to a doubly-linked list + * + * @return psList* A new psList populated with elements formt the psVector, + * or NULL is the given arr parameter is NULL. + */ psList* psVectorToList( - psVector* arr ///< vector to convert + psVector* arr ///< vector to convert ); Index: /trunk/psLib/src/types/psList.c =================================================================== --- /trunk/psLib/src/types/psList.c (revision 1016) +++ /trunk/psLib/src/types/psList.c (revision 1017) @@ -6,6 +6,6 @@ * @author Robert Daniel DeSonia, MHPCC * - * @version $Revision: 1.4 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-06-09 19:50:32 $ + * @version $Revision: 1.5 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-06-12 22:15:39 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii Index: /trunk/psLib/src/types/psList.h =================================================================== --- /trunk/psLib/src/types/psList.h (revision 1016) +++ /trunk/psLib/src/types/psList.h (revision 1017) @@ -10,6 +10,6 @@ * @ingroup LinkedList * - * @version $Revision: 1.3 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-06-10 01:58:06 $ + * @version $Revision: 1.4 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-06-12 22:15:39 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -42,17 +42,21 @@ typedef struct psListElem { - struct psListElem *prev; ///< previous link in list - struct psListElem *next; ///< next link in list + struct psListElem *prev; ///< previous link in list + struct psListElem *next; ///< next link in list void *data; ///< real data item } psListElem; -/** Doubly-linked list */ +/** The psList Linked list structure. User should not allocate this struct + * directly; rather the psListAlloc should be used. + * + * @see psListAlloc, psListFree + */ 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 + 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 @@ -60,72 +64,130 @@ psList; -/** Constructor */ -psList *psListAlloc( - void *data ///< initial data item; may be NULL +/** Creates a psList linked list object. + * + * @return psList* A new psList object. + */ +psList* psListAlloc( + void *data + ///< initial data item; may be NULL if no an empty psList is desired ) ; #include "psMemory.h" -/** Destructor */ +/** Destroys a psList linked list object. This also frees the elements of the + * list using the psFreeFcn given, if any. If no psFreeFcn is specified, + * the elements are just dereferenced via psMemDecrRefCounter(...). + * + */ void psListFree( - psList* restrict list, ///< list to destroy + psList* restrict list, ///< list to destroy psFreeFcn elemFree ///< destructor for data on list ); -/** Add to list */ +/** Adds an element to a psList at position given. + * + * @return psList* The psList with added data item. If list parameter is + * NULL, the return value will also be NULL. + */ psList* psListAdd( - psList* restrict list, ///< list to add to (may be NULL) - void* data, ///< data item to add - int where ///< index, PS_LIST_HEAD, or PS_LIST_TAIL + 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. ); -/** Append to a list */ +/** Appends an item to a psList. + * + * @return psList* The psList with added data item. If list parameter is + * NULL, the return value will also be NULL. + */ psList* psListAppend( - psList* restrict list, ///< list to append to (may be NULL) - void *data ///< data item to add + psList* restrict list, ///< list to append to (if NULL, nothing is done) + void *data ///< data item to add. If NULL, list is not modified. ); -/** Remove from a list */ +/** Remove an item from a list. If which parameter is PS_LIST_UNKNOWN, + * + * @return void* The data item that was removed. If NULL, no item was + * removed. + */ void* psListRemove( - psList* restrict list, ///< list to remove element from - void *data, ///< data item to remove - int which ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV + 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 from a list */ +/** Retrieve an item from a list. + * + * @return void* the item corresponding to the which parameter. If + * which is invalid (e.g., a numbered index greater + * than the list size or if the list is empty), a + * NULL is returned. + */ void* psListGet( psList* restrict list, ///< list to retrieve element from - int which ///< index of item, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN + int which ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN ); -/** Set the iterator */ +/** Set the iterator of the list to a given position. If where is invalid the + * iterator position is not changed. + * + */ void psListSetIterator( psList* restrict list, ///< list to retrieve element from - int where ///< index, PS_LIST_HEAD, or PS_LIST_TAIL + int where ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL ); -/** Get next element relative to iter */ +/** Get next element relative to the iterator. This also moves the iterator to + * the next list position. + * + * @return void* the data item next on the list or NULL if the iterator + * is already pointing to the last element or the list + * parameter was NULL. + */ void* psListGetNext( psList* restrict list ///< list to retrieve element from ); -/** Get current element at iter */ +/** Get current element according to the psList's iterator cursor. This does + * not move the iterator location. + * + * @return void* the data item cooresponding to current iterator + * cursor position of the list, or NULL if either the + * iterator is not valid or list parameter was NULL. + */ void* psListGetCurrent( psList* restrict list ///< list to retrieve element from ); -/** Get prev element relative to iter */ +/** Get previous element relative to list's iterator. This also moves the + * iterator to the previous list position. + * + * @return void* the data item previous on the list or NULL if the iterator + * is already pointing to the first element or the list + * parameter was NULL. + */ void* psListGetPrevious( psList* restrict list ///< list to retrieve element from ); -/** Convert doubly-linked list to an array */ +/** Convert a linked list to an array + * + * @return psVector* A new psVector populated with elements from the list, + * or NULL if the given dlist parameter is NULL. + */ psVector* psListToVector( psList *dlist ///< List to convert ); -/** Convert array to a doubly-linked list */ +/** Convert array to a doubly-linked list + * + * @return psList* A new psList populated with elements formt the psVector, + * or NULL is the given arr parameter is NULL. + */ psList* psVectorToList( - psVector* arr ///< vector to convert + psVector* arr ///< vector to convert );