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

add Doxygen documentation (partially)

Browse Source
This commit is contained in:
marschap
2008-11-28 10:48:39 +00:00
parent 83337fea15
commit 925be143ac
1 changed files with 317 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shared/LL.c
+224 -53
View File
@@ -1,3 +1,19 @@
/** \file LL.c
* Define routines to deal with doubly linked lists
*/
/* This file is part of LCDproc.
*
* This file is released under the GNU General Public License. Refer to the
* COPYING file distributed with this package.
*
* Copyright(c) 1999, William Ferrell
* (c) 2000, Guillaume Filion
* (c) 2001, Joris Robijn
* (c) 2008, Peter Marschall
*
*/
#include <stdlib.h> #include <stdlib.h>
#include <stdio.h> #include <stdio.h>
#include "LL.h" #include "LL.h"
@@ -9,8 +25,10 @@
//TODO: Comment everything //TODO: Comment everything
//TODO: Test everything? //TODO: Test everything?
//////////////////////////////////////////////////////////////////////
// Creates a new list... /** Create new linked list.
* \return Pointer to freshly created list object; \c NULL on error.
*/
LinkedList * LinkedList *
LL_new() LL_new()
{ {
@@ -31,10 +49,15 @@ LL_new ()
return list; return list;
} }
//////////////////////////////////////////////////////////////////////
// TODO: test this function /** Destroy the entire list.
// Destroys the entire list *
// Warning! Does not free the list data! (only the list itself) * Note: this does not free the data, only the list itself
*
* \param list List object to be destroyed.
* \retval <0 error
* \retval 0 success
*/
int int
LL_Destroy(LinkedList *list) LL_Destroy(LinkedList *list)
{ {
@@ -57,9 +80,15 @@ LL_Destroy (LinkedList * list)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
// TODO: test this function /** 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.
* \retval <0 error
* \retval 0 success
*/
int int
LL_node_Destroy(LL_node *node) LL_node_Destroy(LL_node *node)
{ {
@@ -74,7 +103,12 @@ LL_node_Destroy (LL_node * node)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
/** Unlink a node from the list.
* \param node Node to be unlinked.
* \retval <0 error
* \retval 0 success
*/
int int
LL_node_Unlink(LL_node *node) LL_node_Unlink(LL_node *node)
{ {
@@ -97,23 +131,35 @@ LL_node_Unlink (LL_node * node)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
// Frees the data in a list node, if not NULL... /** Free the data in a list node.
* \param node Node, whose data is to be destroyed.
* \retval <0 error: illegal node, or no node data to destroy.
* \retval 0 success
*/
int int
LL_node_DestroyData(LL_node *node) LL_node_DestroyData(LL_node *node)
{ {
if (!node) if (!node)
return -1; return -1;
if (node->data) if (node->data) {
free(node->data); free(node->data);
// prevent accidential double free()
node->data = NULL;
}
else else
return -1; return -1;
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
// Returns 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.
* \param list List object.
* \retval <0 error: no list given
* \retval 0 success
*/
int int
LL_Rewind(LinkedList *list) LL_Rewind(LinkedList *list)
{ {
@@ -133,8 +179,13 @@ LL_Rewind (LinkedList * list)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
// Goes 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.
* \param list List object.
* \retval <0 error: no list given
* \retval 0 success
*/
int int
LL_End(LinkedList *list) LL_End(LinkedList *list)
{ {
@@ -149,8 +200,13 @@ LL_End (LinkedList * list)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
// Go to the next node /** Go to the next node of the list.
* Advance list's "current" pointer to the next node in the list.
* \param list List object.
* \retval <0 error: no list given or no next node
* \retval 0 success
*/
int int
LL_Next(LinkedList *list) LL_Next(LinkedList *list)
{ {
@@ -167,8 +223,13 @@ LL_Next (LinkedList * list)
} }
} }
//////////////////////////////////////////////////////////////////////
// Go to the previous node /** Go to the previous node of the list.
* Set list's "current" pointer to the previous node in the list.
* \param list List object.
* \retval <0 error: no list given or no previous node
* \retval 0 success
*/
int int
LL_Prev(LinkedList *list) LL_Prev(LinkedList *list)
{ {
@@ -185,8 +246,12 @@ LL_Prev (LinkedList * list)
} }
} }
//////////////////////////////////////////////////////////////////////
// Data manipulation /** Access current node's data.
* \param list List object.
* \retval <0 error: no list given, or no data in current node
* \retval 0 success
*/
void * void *
LL_Get(LinkedList *list) LL_Get(LinkedList *list)
{ {
@@ -198,7 +263,13 @@ LL_Get (LinkedList * list)
return list->current->data; return list->current->data;
} }
//////////////////////////////////////////////////////////////////////
/** Set/change current node's data.
* \param list List object.
* \param data Pointer to data to be set.
* \retval <0 error: no list given, or no current node
* \retval 0 success
*/
int int
LL_Put(LinkedList *list, void *data) LL_Put(LinkedList *list, void *data)
{ {
@@ -212,7 +283,11 @@ LL_Put (LinkedList * list, void *data)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
/** Get current node in list.
* \param list List object.
* \return Pointer to current node.
*/
LL_node * LL_node *
LL_GetNode(LinkedList *list) LL_GetNode(LinkedList *list)
{ {
@@ -222,8 +297,16 @@ LL_GetNode (LinkedList * list)
return list->current; return list->current;
} }
//////////////////////////////////////////////////////////////////////
// Don't use this unless you know what you're doing. /** Set list's current pointr to a specific node.
*
* Warning: Don't use this unless you know what you're doing.
*
* \param list List object.
* \param list List object.
* \retval <0 error
* \retval 0 success
*/
int int
LL_PutNode(LinkedList *list, LL_node *node) LL_PutNode(LinkedList *list, LL_node *node)
{ {
@@ -237,9 +320,14 @@ LL_PutNode (LinkedList * list, LL_node * node)
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
/** Access list's first node's data.
* Set list's "current" pointer to the first node and return its data.
* \param list List object.
* \return Pointer to first node's data; \c NULL on error.
*/
void * void *
LL_GetFirst (LinkedList * list) // gets data from first node LL_GetFirst(LinkedList *list)
{ {
if (!list) if (!list)
return NULL; return NULL;
@@ -250,10 +338,14 @@ LL_GetFirst (LinkedList * list) // gets data from first node
return LL_Get(list); return LL_Get(list);
} }
//////////////////////////////////////////////////////////////////////
// /** Access next node's data.
* Advance list's "current" pointer to the next node and return its data.
* \param list List object.
* \return Pointer to next node's data; \c NULL on error.
*/
void * void *
LL_GetNext (LinkedList * list) // ... next node LL_GetNext(LinkedList *list)
{ {
if (!list) if (!list)
return NULL; return NULL;
@@ -264,9 +356,14 @@ LL_GetNext (LinkedList * list) // ... next node
return LL_Get(list); return LL_Get(list);
} }
//////////////////////////////////////////////////////////////////////
/** Access previous node's data.
* Set list's "current" pointer to the previous node, and return its data.
* \param list List object.
* \return Pointer to previous node's data; \c NULL on error.
*/
void * void *
LL_GetPrev (LinkedList * list) // ... prev node LL_GetPrev(LinkedList *list)
{ {
if (!list) if (!list)
return NULL; return NULL;
@@ -277,9 +374,14 @@ LL_GetPrev (LinkedList * list) // ... prev node
return LL_Get(list); return LL_Get(list);
} }
//////////////////////////////////////////////////////////////////////
/** Access list's last node's data.
* Set list's "current" pointer to the last node and return its data.
* \param list List object.
* \return Pointer to last node's data; \c NULL on error.
*/
void * void *
LL_GetLast (LinkedList * list) // ... last node LL_GetLast(LinkedList *list)
{ {
if (!list) if (!list)
return NULL; return NULL;
@@ -290,9 +392,15 @@ LL_GetLast (LinkedList * list) // ... last node
return LL_Get(list); return LL_Get(list);
} }
//////////////////////////////////////////////////////////////////////
/** Add/append a new node after current one in the list.
* \param list List object.
* \param add Pointer to new node's data.
* \retval <0 error
* \retval 0 success
*/
int int
LL_AddNode (LinkedList * list, void *add) // Adds node AFTER current one LL_AddNode(LinkedList *list, void *add)
{ {
LL_node *node; LL_node *node;
@@ -346,9 +454,15 @@ LL_AddNode (LinkedList * list, void *add) // Adds node AFTER current one
return 0; return 0;
} }
//////////////////////////////////////////////////////////////////////
/** Add/insert a new node before current one in the list.
* \param list List object.
* \param add Pointer to new node's data.
* \retval <0 error
* \retval 0 success
*/
int int
LL_InsertNode (LinkedList * list, void *add) // Adds node BEFORE current one LL_InsertNode(LinkedList *list, void *add)
{ {
LL_node *node; LL_node *node;
@@ -431,8 +545,13 @@ LL_DeleteNode (LinkedList * list)
return data; return data;
} }
//////////////////////////////////////////////////////////////////////
// Removes a specific node... /** Remove a specific node from the list.
* find a node by a pointer to it's data and remove it.
* \param list List object.
* \param data Pointer to data of not to delete.
* \return Pointer to data of deleted node; \c NULL on error.
*/
void * void *
LL_Remove(LinkedList *list, void *data) LL_Remove(LinkedList *list, void *data)
{ {
@@ -451,8 +570,14 @@ LL_Remove (LinkedList * list, void *data)
return NULL; return NULL;
} }
//////////////////////////////////////////////////////////////////////
// Stack operations /** 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.
* \param list List object.
* \param add Pointer to new node's data.
* \retval <0 error
* \retval 0 success
*/
int int
LL_Push(LinkedList *list, void *add) // Add node to end of list LL_Push(LinkedList *list, void *add) // Add node to end of list
{ {
@@ -468,7 +593,12 @@ LL_Push (LinkedList * list, void *add) // Add node to end of list
return LL_AddNode(list, add); return LL_AddNode(list, add);
} }
//////////////////////////////////////////////////////////////////////
/** 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.
* \param list List object.
* \return Pointer to data of deleted node; \c NULL on error.
*/
void * void *
LL_Pop(LinkedList *list) // Remove node from end of list LL_Pop(LinkedList *list) // Remove node from end of list
{ {
@@ -481,14 +611,24 @@ LL_Pop (LinkedList * list) // Remove node from end of list
return LL_DeleteNode(list); return LL_DeleteNode(list);
} }
//////////////////////////////////////////////////////////////////////
/** Access list's last node's data.
* Set list's "current" pointer to the last node and return its data.
* \param list List object.
* \return Pointer to last node's data; \c NULL on error.
*/
void * void *
LL_Top(LinkedList *list) // Peek at end node LL_Top(LinkedList *list) // Peek at end node
{ {
return LL_GetLast(list); return LL_GetLast(list);
} }
//////////////////////////////////////////////////////////////////////
/** Remove the first node from the list, and return its data.
* Jump to the first node in the list, remove it from the list and return its data.
* \param list List object.
* \return Pointer to data of deleted node; \c NULL on error.
*/
void * void *
LL_Shift(LinkedList *list) // Remove node from start of list LL_Shift(LinkedList *list) // Remove node from start of list
{ {
@@ -501,14 +641,26 @@ LL_Shift (LinkedList * list) // Remove node from start of list
return LL_DeleteNode(list); return LL_DeleteNode(list);
} }
//////////////////////////////////////////////////////////////////////
/** Access list's first node's data.
* Set list's "current" pointer to the first node and return its data.
* \param list List object.
* \return Pointer to first node's data; \c NULL on error.
*/
void * void *
LL_Look(LinkedList *list) // Peek at first node LL_Look(LinkedList *list) // Peek at first node
{ {
return LL_GetFirst(list); return LL_GetFirst(list);
} }
//////////////////////////////////////////////////////////////////////
/** Add/insert a new node before the first one in the list.
* Jump to the first node in the list and insert a new node before that one.
* \param list List object.
* \param add Pointer to new node's data.
* \retval <0 error
* \retval 0 success
*/
int int
LL_Unshift(LinkedList *list, void *add) // Add node to beginning of list LL_Unshift(LinkedList *list, void *add) // Add node to beginning of list
{ {
@@ -522,6 +674,7 @@ LL_Unshift (LinkedList * list, void *add) // Add node to beginning of list
return LL_InsertNode(list, add); return LL_InsertNode(list, add);
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
int int
LL_Roll(LinkedList *list) // Make last node first LL_Roll(LinkedList *list) // Make last node first
@@ -564,6 +717,7 @@ LL_Roll (LinkedList * list) // Make last node first
return 0; return 0;
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
int int
LL_UnRoll(LinkedList *list) // Roll the other way... LL_UnRoll(LinkedList *list) // Roll the other way...
@@ -606,6 +760,7 @@ LL_UnRoll (LinkedList * list) // Roll the other way...
return 0; return 0;
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
// 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...
@@ -643,6 +798,7 @@ LL_PriorityEnqueue (LinkedList * list, void *add, int compare (void *, void *))
return 0; return 0;
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
int int
LL_SwapNodes(LL_node *one, LL_node *two) // Switch two nodes positions... LL_SwapNodes(LL_node *one, LL_node *two) // Switch two nodes positions...
@@ -687,6 +843,7 @@ LL_SwapNodes (LL_node * one, LL_node * two) // Switch two nodes positions...
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
int int
LL_nSwapNodes(int one, int two) // Switch two nodes positions... LL_nSwapNodes(int one, int two) // Switch two nodes positions...
@@ -694,7 +851,11 @@ LL_nSwapNodes (int one, int two) // Switch two nodes positions...
return -1; return -1;
} }
//////////////////////////////////////////////////////////////////////
/** Calculate the length of a list.
* \param list List object.
* \return Number of nodes in the list; \c -1 on error.
*/
int int
LL_Length(LinkedList *list) // Returns # of nodes in entire list LL_Length(LinkedList *list) // Returns # of nodes in entire list
{ {
@@ -712,6 +873,7 @@ LL_Length (LinkedList * list) // Returns # of nodes in entire list
return num; return num;
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
// Searching... // Searching...
// Goes to the list item which matches "value", and returns the // Goes to the list item which matches "value", and returns the
@@ -743,6 +905,7 @@ LL_Find (LinkedList * list, int compare (void *, void *), void *value)
return NULL; return NULL;
} }
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
// Array like... // Array like...
// Goes to the nth list item, and returns the // Goes to the nth list item, and returns the
@@ -767,9 +930,17 @@ LL_GetByIndex (LinkedList * list, int index)
return NULL; // got past the end return NULL; // got past the end
} }
//////////////////////////////////////////////////////////////////////
// Sorts the list, then rewinds it... /** Sort list by its contents.
// * The list gets sorted using a comparison function for the data of its nodes.
* After the sorting, the list's current pointer is set to the first node.
* \param list List object.
* \param compare Pointer to a comparison function, that takes to void pointers
is arguments and returns an int > 0 when the first argument
is considered greater then the second.
* \retval <0 error
* \retval 0 success.
*/
int int
LL_Sort(LinkedList *list, int compare(void *, void *)) LL_Sort(LinkedList *list, int compare(void *, void *))
{ {