mangavalk/lcdproc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

better Doxygen comments, a bit of cleanup

Browse Source
This commit is contained in:
marschap
2008-11-30 14:01:28 +00:00
parent d6ac9b559d
commit f50630c566
2 changed files with 115 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shared/LL.c
+63 -65
View File
@@ -4,8 +4,8 @@
/* This file is part of LCDproc. /* This file is part of LCDproc.
* *
* This file is released under the GNU General Public License. Refer to the * This file is released under the GNU General Public License.
* COPYING file distributed with this package. * Refer to the COPYING file distributed with this package.
* *
* Copyright(c) 1999, William Ferrell * Copyright(c) 1999, William Ferrell
* (c) 2000, Guillaume Filion * (c) 2000, Guillaume Filion
@@ -82,7 +82,8 @@ LL_Destroy(LinkedList *list)
/** Destroy a node. /** Destroy a node.
* *
* Warning! This does not assert that the node data is free! * \warning
* This does not assert that the node data is free!
* *
* \param node Node to be destroyed. * \param node Node to be destroyed.
* \retval <0 error * \retval <0 error
@@ -154,7 +155,7 @@ LL_node_DestroyData(LL_node *node)
/* Return to the beginning of the list. /* Return to the beginning of the list.
* Set list's "current" pointer to the first node in the list. * Set list's \c current pointer to the first node in the list.
* \param list List object. * \param list List object.
* \retval <0 error: no list given * \retval <0 error: no list given
* \retval 0 success * \retval 0 success
@@ -165,17 +166,16 @@ LL_Rewind(LinkedList *list)
if (!list) if (!list)
return -1; return -1;
if (list->head.next != &list->tail) list->current = (list->head.next != &list->tail)
list->current = list->head.next; ? list->head.next
else : &list->head;
list->current = &list->head;
return 0; return 0;
} }
/** Jump to the end of the list. /** Jump to the end of the list.
* Set list's "current" pointer to the last node in the list. * Set list's \c current pointer to the last node in the list.
* \param list List object. * \param list List object.
* \retval <0 error: no list given * \retval <0 error: no list given
* \retval 0 success * \retval 0 success
@@ -186,17 +186,16 @@ LL_End(LinkedList *list)
if (!list) if (!list)
return -1; return -1;
if (list->tail.prev != &list->head) list->current = (list->tail.prev != &list->head)
list->current = list->tail.prev; ? list->tail.prev
else : &list->tail;
list->current = &list->tail;
return 0; return 0;
} }
/** Go to the next node of the list. /** Go to the next node of the list.
* Advance list's "current" pointer to the next node in the list. * Advance list's \c current pointer to the next node in the list.
* \param list List object. * \param list List object.
* \retval <0 error: no list given or no next node * \retval <0 error: no list given or no next node
* \retval 0 success * \retval 0 success
@@ -209,17 +208,16 @@ LL_Next(LinkedList *list)
if (!list->current) if (!list->current)
return -1; return -1;
if (list->current->next != &list->tail) { if (list->current->next == &list->tail)
return -1;
list->current = list->current->next; list->current = list->current->next;
return 0; return 0;
} else {
return -1;
}
} }
/** Go to the previous node of the list. /** Go to the previous node of the list.
* Set list's "current" pointer to the previous node in the list. * Set list's \c current pointer to the previous node in the list.
* \param list List object. * \param list List object.
* \retval <0 error: no list given or no previous node * \retval <0 error: no list given or no previous node
* \retval 0 success * \retval 0 success
@@ -232,19 +230,19 @@ LL_Prev(LinkedList *list)
if (!list->current) if (!list->current)
return -1; return -1;
if (list->current->prev != &list->head) { if (list->current->prev == &list->head)
return -1;
list->current = list->current->prev; list->current = list->current->prev;
return 0; return 0;
} else {
return -1;
}
} }
/** Access current node's data. /** Access current node's data.
* Return pointer to list's \c current node's data.
* \param list List object. * \param list List object.
* \retval <0 error: no list given, or no data in current node * \return Pointer to \c current node's payload data;
* \retval 0 success * \c NULL may be empty payload or an error.
*/ */
void * void *
LL_Get(LinkedList *list) LL_Get(LinkedList *list)
@@ -292,12 +290,13 @@ LL_GetNode(LinkedList *list)
} }
/** Set list's current pointr to a specific node. /** Set list's \c current pointer to a specific node.
* *
* Warning: Don't use this unless you know what you're doing. * \warning
* Don't use this unless you know what you're doing.
* *
* \param list List object. * \param list List object.
* \param list List object. * \param node Node to become new \c current.
* \retval <0 error * \retval <0 error
* \retval 0 success * \retval 0 success
*/ */
@@ -316,7 +315,7 @@ LL_PutNode(LinkedList *list, LL_node *node)
/** Access list's first node's data. /** Access list's first node's data.
* Set list's "current" pointer to the first node and return its data. * Set list's \c current pointer to the first node and return its data.
* \param list List object. * \param list List object.
* \return Pointer to first node's data; \c NULL on error. * \return Pointer to first node's data; \c NULL on error.
*/ */
@@ -334,7 +333,7 @@ LL_GetFirst(LinkedList *list)
/** Access next node's data. /** Access next node's data.
* Advance list's "current" pointer to the next node and return its data. * Advance list's \c current pointer to the next node and return its data.
* \param list List object. * \param list List object.
* \return Pointer to next node's data; \c NULL on error. * \return Pointer to next node's data; \c NULL on error.
*/ */
@@ -352,7 +351,7 @@ LL_GetNext(LinkedList *list)
/** Access previous node's data. /** Access previous node's data.
* Set list's "current" pointer to the previous node, and return its data. * Set list's \c current pointer to the previous node, and return its data.
* \param list List object. * \param list List object.
* \return Pointer to previous node's data; \c NULL on error. * \return Pointer to previous node's data; \c NULL on error.
*/ */
@@ -370,7 +369,7 @@ LL_GetPrev(LinkedList *list)
/** Access list's last node's data. /** Access list's last node's data.
* Set list's "current" pointer to the last node and return its data. * Set list's \c current pointer to the last node and return its data.
* \param list List object. * \param list List object.
* \return Pointer to last node's data; \c NULL on error. * \return Pointer to last node's data; \c NULL on error.
*/ */
@@ -388,6 +387,7 @@ LL_GetLast(LinkedList *list)
/** Add/append a new node after current one in the list. /** Add/append a new node after current one in the list.
* Update the list's \c current pointer to point to the freshly created node.
* \param list List object. * \param list List object.
* \param add Pointer to new node's data. * \param add Pointer to new node's data.
* \retval <0 error * \retval <0 error
@@ -400,7 +400,6 @@ LL_AddNode(LinkedList *list, void *add)
if (!list) if (!list)
return -1; return -1;
//if(!add) return -1; // Nevermind.. NULL entries can be good...
if (!list->current) if (!list->current)
return -1; return -1;
@@ -408,9 +407,10 @@ LL_AddNode(LinkedList *list, void *add)
if (node == NULL) if (node == NULL)
return -1; return -1;
if (list->current == &list->tail) { // we're behind the list's end, go to previous node
if (list->current == &list->tail)
list->current = list->current->prev; list->current = list->current->prev;
}
// Set node data // Set node data
node->next = list->current->next; node->next = list->current->next;
node->prev = list->current; node->prev = list->current;
@@ -419,7 +419,6 @@ LL_AddNode(LinkedList *list, void *add)
// Re-link // Re-link
if (node->next) if (node->next)
node->next->prev = node; node->next->prev = node;
list->current->next = node; list->current->next = node;
list->current = node; list->current = node;
@@ -429,6 +428,7 @@ LL_AddNode(LinkedList *list, void *add)
/** Add/insert a new node before current one in the list. /** Add/insert a new node before current one in the list.
* Update the list's \c current pointer to point to the freshly created node.
* \param list List object. * \param list List object.
* \param add Pointer to new node's data. * \param add Pointer to new node's data.
* \retval <0 error * \retval <0 error
@@ -450,6 +450,7 @@ LL_InsertNode(LinkedList *list, void *add)
if (node == NULL) if (node == NULL)
return -1; return -1;
// we're before the list's start, go to next node
if (list->current == &list->head) if (list->current == &list->head)
list->current = list->current->next; list->current = list->current->next;
@@ -459,7 +460,6 @@ LL_InsertNode(LinkedList *list, void *add)
if (list->current->prev) if (list->current->prev)
list->current->prev->next = node; list->current->prev->next = node;
list->current->prev = node; list->current->prev = node;
list->current = node; list->current = node;
@@ -469,7 +469,7 @@ LL_InsertNode(LinkedList *list, void *add)
/** Remove current node from the list. /** Remove current node from the list.
* Set the current pointer to the node after the deleted one. * Set the list's \c current pointer to the node after the deleted one.
* \param list List object. * \param list List object.
* \return Pointer to data of deleted node; \c NULL on error. * \return Pointer to data of deleted node; \c NULL on error.
*/ */
@@ -514,7 +514,7 @@ LL_DeleteNode(LinkedList *list)
/** Remove a specific node from the list. /** Remove a specific node from the list.
* Find a node by a pointer to its data and remove it. * Find a node by a pointer to its data and remove it.
* After te deletion the "current" pointer is on the node after the deleted one. * After the deletion the \c current pointer is on the node after the deleted one.
* \param list List object. * \param list List object.
* \param data Pointer to data of node to delete. * \param data Pointer to data of node to delete.
* \return Pointer to data of deleted node; \c NULL on error. * \return Pointer to data of deleted node; \c NULL on error.
@@ -527,7 +527,7 @@ LL_Remove(LinkedList *list, void *data)
LL_Rewind(list); LL_Rewind(list);
do { do {
void * find = LL_Get(list); void *find = LL_Get(list);
if (find == data) if (find == data)
return LL_DeleteNode(list); return LL_DeleteNode(list);
@@ -538,7 +538,8 @@ LL_Remove(LinkedList *list, void *data)
/** Add/append a new node after the last one in the list. /** Add/append a new node after the last one in the list.
* Jump to the last node in the list and append a new node. * Jump to the last node in the list, append a new node
* and make this new one the list's \c current one.
* \param list List object. * \param list List object.
* \param add Pointer to new node's data. * \param add Pointer to new node's data.
* \retval <0 error * \retval <0 error
@@ -559,7 +560,8 @@ LL_Push(LinkedList *list, void *add) // Add node to end of list
/** Remove the last node from the list, and return its data. /** Remove the last node from the list, and return its data.
* Jump to the last node in the list, remove it from the list and return its data. * Jump to the last node in the list, remove it from the list
* and return its data.
* \param list List object. * \param list List object.
* \return Pointer to data of deleted node; \c NULL on error. * \return Pointer to data of deleted node; \c NULL on error.
*/ */
@@ -577,7 +579,7 @@ LL_Pop(LinkedList *list) // Remove node from end of list
/** Access list's last node's data. /** Access list's last node's data.
* Set list's "current" pointer to the last node and return its data. * Set list's \c current pointer to the last node and return its data.
* \param list List object. * \param list List object.
* \return Pointer to last node's data; \c NULL on error. * \return Pointer to last node's data; \c NULL on error.
*/ */
@@ -607,7 +609,7 @@ LL_Shift(LinkedList *list) // Remove node from start of list
/** Access list's first node's data. /** Access list's first node's data.
* Set list's "current" pointer to the first node and return its data. * Set list's \c current pointer to the first node and return its data.
* \param list List object. * \param list List object.
* \return Pointer to first node's data; \c NULL on error. * \return Pointer to first node's data; \c NULL on error.
*/ */
@@ -729,11 +731,8 @@ LL_UnRoll(LinkedList *list) // Roll the other way...
// Add an item to the end of its "priority group" // Add an item to the end of its "priority group"
// The list is assumed to be sorted already... // The list is assumed to be sorted already...
int int
LL_PriorityEnqueue(LinkedList *list, void *add, int compare(void *, void *)) LL_PriorityEnqueue(LinkedList *list, void *add, int (*compare)(void *, void *))
{ {
void *data;
int i;
if (!list) if (!list)
return -1; return -1;
if (!add) if (!add)
@@ -745,11 +744,12 @@ LL_PriorityEnqueue(LinkedList *list, void *add, int compare(void *, void *))
// the given nodes... // the given nodes...
LL_End(list); LL_End(list);
do { do {
data = LL_Get(list); void *data = LL_Get(list);
if (data) { if (data) {
i = compare(add, data); int i = compare(add, data);
if (i >= 0) // If we're in the right place, add it and exit
{ if (i >= 0) { // If we're in the right place, add it and exit
LL_AddNode(list, add); LL_AddNode(list, add);
return 0; return 0;
} }
@@ -804,7 +804,6 @@ LL_SwapNodes(LL_node *one, LL_node *two) // Switch two nodes positions...
two->prev = one; two->prev = one;
return 0; return 0;
} }
@@ -842,21 +841,20 @@ LL_Length(LinkedList *list)
* Go to to the list node whose data matches the given value * Go to to the list node whose data matches the given value
* and return the data. * and return the data.
* *
* Note that this does *not* rewind the list first! * \note
* This does \em not rewind the list first!
* Do it yourself if you want to start from the beginning! * Do it yourself if you want to start from the beginning!
* *
* \param list List object. * \param list List object.
* \param compare Pointer to a comparison function, that takes to void pointers * \param compare Pointer to a comparison function, that takes to void pointers
* is arguments and returns an int. If must return 0 exactly when * as arguments and returns an int. If must return \c 0 exactly
* the node's data matches \c value. * when the node's data matches \c value.
* \param value Pointer to the value used for matching. * \param value Pointer to the value used for matching.
* \return The found node's data pointer; \c NULL otherwise * \return The found node's data pointer; \c NULL otherwise
*/ */
void * void *
LL_Find(LinkedList *list, int compare(void *, void *), void *value) LL_Find(LinkedList *list, int (*compare)(void *, void *), void *value)
{ {
void *data;
if (!list) if (!list)
return NULL; return NULL;
if (!compare) if (!compare)
@@ -865,10 +863,10 @@ LL_Find(LinkedList *list, int compare(void *, void *), void *value)
return NULL; return NULL;
do { do {
data = LL_Get(list); void *data = LL_Get(list);
if (0 == compare(data, value)) if (0 == compare(data, value))
return data; return data;
} while (LL_Next(list) == 0); } while (LL_Next(list) == 0);
return NULL; return NULL;
@@ -888,7 +886,7 @@ LL_GetByIndex(LinkedList *list, int index)
if (!list) if (!list)
return NULL; return NULL;
if (index<0) if (index < 0)
return NULL; return NULL;
for (node = list->head.next; node != &list->tail; node = node->next) { for (node = list->head.next; node != &list->tail; node = node->next) {
@@ -905,13 +903,13 @@ LL_GetByIndex(LinkedList *list, int index)
* After the sorting, the list's current pointer is set to the first node. * After the sorting, the list's current pointer is set to the first node.
* \param list List object. * \param list List object.
* \param compare Pointer to a comparison function, that takes to void pointers * \param compare Pointer to a comparison function, that takes to void pointers
* is arguments and returns an int > 0 when the first argument * as arguments and returns an int > \c 0 when the first argument
* is considered greater then the second. * is considered greater than the second.
* \retval <0 error * \retval <0 error
* \retval 0 success. * \retval 0 success.
*/ */
int int
LL_Sort(LinkedList *list, int compare(void *, void *)) LL_Sort(LinkedList *list, int (*compare)(void *, void *))
{ {
int i, j; // Junk / loop variables int i, j; // Junk / loop variables
int numnodes; // number of nodes in list int numnodes; // number of nodes in list
shared/LL.h
+48 -42
View File
@@ -115,62 +115,69 @@
// See LL.c for more detailed descriptions of these functions. // See LL.c for more detailed descriptions of these functions.
/** Structure for a node in a linked list */
typedef struct LL_node { typedef struct LL_node {
struct LL_node *next, *prev; struct LL_node *prev; /**< Pointer to previous node */
void *data; struct LL_node *next; /**< Pointer to next node */
void *data; /**< Payload */
} LL_node; } LL_node;
/** Structire for a linked list */
typedef struct LinkedList { typedef struct LinkedList {
LL_node head, tail; LL_node head; /**< List's head anchor */
LL_node *current; LL_node tail; /**< List's tail anchor */
LL_node *current; /**< Pointer to current node */
} LinkedList; } LinkedList;
// Creates a new list... // Creates a new list...
LinkedList *LL_new (); LinkedList *LL_new(void);
// Destroying lists... // Destroying lists...
int LL_Destroy (LinkedList * list); int LL_Destroy(LinkedList *list);
int LL_node_Destroy (LL_node * node); int LL_node_Destroy(LL_node *node);
int LL_node_Unlink (LL_node * node); int LL_node_Unlink(LL_node *node);
int LL_node_DestroyData (LL_node * node); int LL_node_DestroyData(LL_node *node);
// Returns to the beginning of the list... // Returns to the beginning of the list...
int LL_Rewind (LinkedList * list); int LL_Rewind(LinkedList *list);
// Goes to the end of the list... // Goes to the end of the list...
int LL_End (LinkedList * list); int LL_End(LinkedList *list);
// Go to the next node // Go to the next node
int LL_Next (LinkedList * list); int LL_Next(LinkedList *list);
// Go to the previous node // Go to the previous node
int LL_Prev (LinkedList * list); int LL_Prev(LinkedList *list);
// Data manipulation // Data manipulation
void *LL_Get (LinkedList * list); void *LL_Get(LinkedList *list);
int LL_Put (LinkedList * list, void *data); int LL_Put(LinkedList *list, void *data);
// Don't use these next two unless you really know what you're doing. // Don't use these next two unless you really know what you're doing.
LL_node *LL_GetNode (LinkedList * list); LL_node *LL_GetNode(LinkedList *list);
int LL_PutNode (LinkedList * list, LL_node * node); int LL_PutNode(LinkedList *list, LL_node *node);
void *LL_GetFirst (LinkedList * list); // gets data from first node void *LL_GetFirst(LinkedList *list); // gets data from first node
void *LL_GetNext (LinkedList * list); // ... next node void *LL_GetNext(LinkedList *list); // ... next node
void *LL_GetPrev (LinkedList * list); // ... prev node void *LL_GetPrev(LinkedList *list); // ... prev node
void *LL_GetLast (LinkedList * list); // ... last node void *LL_GetLast(LinkedList *list); // ... last node
int LL_AddNode (LinkedList * list, void *add); // Adds node AFTER current one int LL_AddNode(LinkedList *list, void *add); // Adds node AFTER current one
int LL_InsertNode (LinkedList * list, void *add); // Adds node BEFORE current one int LL_InsertNode(LinkedList *list, void *add); // Adds node BEFORE current one
// Removes a node from the link; returns the data from the node // Removes a node from the link; returns the data from the node
void *LL_DeleteNode (LinkedList * list); void *LL_DeleteNode(LinkedList *list);
// Removes a specific node... // Removes a specific node...
void *LL_Remove (LinkedList * list, void *data); void *LL_Remove(LinkedList *list, void *data);
// Stack operations // Stack operations
int LL_Push (LinkedList * list, void *add); // Add node to end of list int LL_Push(LinkedList *list, void *add); // Add node to end of list
void *LL_Pop (LinkedList * list); // Remove node from end of list void *LL_Pop(LinkedList *list); // Remove node from end of list
void *LL_Top (LinkedList * list); // Peek at end node void *LL_Top(LinkedList *list); // Peek at end node
void *LL_Shift (LinkedList * list); // Remove node from start of list void *LL_Shift(LinkedList *list); // Remove node from start of list
void *LL_Look (LinkedList * list); // Peek at first node void *LL_Look(LinkedList *list); // Peek at first node
int LL_Unshift (LinkedList * list, void *add); // Add node to beginning of list int LL_Unshift(LinkedList *list, void *add); // Add node to beginning of list
int LL_Roll (LinkedList * list); // Make first node last int LL_Roll(LinkedList *list); // Make first node last
int LL_UnRoll (LinkedList * list); // Roll the other way... int LL_UnRoll(LinkedList *list); // Roll the other way...
// Queue operations... // Queue operations...
//int LL_Enqueue(LinkedList *list, void *add); //int LL_Enqueue(LinkedList *list, void *add);
@@ -178,26 +185,25 @@ int LL_UnRoll (LinkedList * list); // Roll the other way...
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
// Queue operations... // Queue operations...
#define LL_Enqueue(list,add) LL_Push(list,add) #define LL_Enqueue(list,add) LL_Push(list,add)
#define LL_Dequeue(list) LL_Shift(list) #define LL_Dequeue(list) LL_Shift(list)
int LL_PriorityEnqueue (LinkedList * list, void *add, int compare (void *, void *)); int LL_PriorityEnqueue (LinkedList * list, void *add, int (*compare)(void *, void *));
int LL_SwapNodes (LL_node * one, LL_node * two); // Switch two nodes positions... int LL_SwapNodes(LL_node *one, LL_node *two); // Switch two nodes positions...
int LL_nSwapNodes (int one, int two); // Switch two nodes positions... int LL_nSwapNodes(int one, int two); // Switch two nodes positions...
int LL_Length (LinkedList * list); // Returns # of nodes in entire list int LL_Length(LinkedList *list); // Returns # of nodes in entire list
// Searching... // Searching...
void *LL_Find (LinkedList * list, int compare (void *, void *), void *value); void *LL_Find(LinkedList *list, int (*compare)(void *, void *), void *value);
// Array operation... // Array operation...
void *LL_GetByIndex (LinkedList * list, int index); // gets the nth node, 0 being the first void *LL_GetByIndex(LinkedList *list, int index); // gets the nth node, 0 being the first
// Sorts the list... // Sorts the list...
int LL_Sort (LinkedList * list, int compare (void *, void *)); int LL_Sort(LinkedList *list, int (*compare)(void *, void *));
// Debugging... // Debugging...
void LL_dprint (LinkedList * list); void LL_dprint(LinkedList *list);
#endif #endif