Main Page | Data Structures | File List | Data Fields | Globals

doubleLinkedList.c File Reference

Fault-tolerant double linked list data structure. More...

Go to the source code of this file.

Data Structures

struct  listNode
struct  List

Defines

#define DOUBLELINKEDLIST_VERSION   "1.1.1"
#define DOUBLELINKEDLIST_DATE   "04-Dec-2003"
#define DOUBLELINKEDLIST_DEBUG   0
 If DOUBLELINKESLIST_DEBUG is set to 1 some debug information is written to standard error.

#define BOOLEAN_FALSE   0
 Boolean variables are simulated with the defines BOOLEAN_FALSE and BOOLEAN_TRUE.

#define BOOLEAN_TRUE   1
 Boolean variables are simulated with the defines BOOLEAN_FALSE and BOOLEAN_TRUE.

#define List_pushhead(listPtr, data)   ( List_insertHead( listPtr, data ) )
 Pushes an element on top of a stack.

#define List_pophead(listPtr)   ( List_removeHead( listPtr ) )
 Pops an element from top of a stack.

#define List_top(listPtr)
 Returns the element on top of a stack without removing it.

#define List_enqueue(listPtr, data)   ( List_insertTail( listPtr, data ) )
 Enqueues an element in a queue.

#define List_dequeue(listPtr)   ( List_removeHead( listPtr ) )
 Dequeues an element of a queue.


Typedefs

typedef listNode ListNode
 A structure listNode is assigned the name ListNode.

typedef ListNodeListNode_Ptr
 A pointer to structure ListNode is assigned the name ListNode_Ptr.

typedef ListList_Ptr
 A pointer to structure List is assigned the name List_Ptr.


Functions

List_Ptr List_create (const int uniqueData, void(*displayFunction)(void *data, FILE *outputStream),\void(*destroyFunction)(void *data),\int(*compareFunction)(const void *data1, const void *data2))
 Creates an List structure.

void List_destroy (List_Ptr listPtr)
 Destroys a List structure.

void List_display (const List_Ptr listPtr, FILE *outputStream)
 Displays a structure List.

void * List_getNext (const List_Ptr listPtr)
 Returns the data of the next node in the list.

int List_hasNext (const List_Ptr listPtr)
 Checks if the List has at least one more node (directed forwards).

void List_rewind (const List_Ptr listPtr)
 Re-sets the position pointer of the List to the beginning of the list.

int List_insert (const List_Ptr listPtr, void *data)
 A new node is inserted in List at the position that is referred by currentNodePtr.

void * List_remove (const List_Ptr listPtr)
 The node that is referred to by currentNodePtr is removed from List and its data is returned.

int List_insertHead (const List_Ptr listPtr, void *data)
 Inserts a node at the head of the List.

int List_insertTail (const List_Ptr listPtr, void *data)
 Inserts a node at the tail of the List.

void * List_removeHead (const List_Ptr listPtr)
 The first node of the structure List is removed.

void * List_removeTail (const List_Ptr listPtr)
 The last node of the structure List is removed.

int List_isEmpty (const List_Ptr listPtr)
 Checks if the structure List is empty.

int List_isContained (const List_Ptr listPtr, const void *data)
 Checks if data is contained in the List.

int List_getNumberOfNodes (const List_Ptr listPtr)
 The numberOfNodes of the List is returned.

void List_setName (const List_Ptr listPtr, char *name)
 Sets the name of the List.

char * List_getName (const List_Ptr listPtr)
 The name of the List is returned.

int List_getUniqueData (const List_Ptr listPtr)
 The value of the member uniqueData of the List is returned.


Detailed Description

Fault-tolerant double linked list data structure.

This structure provides a fault-tolerant data structure of a double linked list. Basically, a double linked list is a dynamic data structure. This implementation facilitates insertions and removals of nodes. A queue and a stack are emulated with 'define' functions (see below).

Two structures are used to implement the list:

The structure is created with List_create, destroyed with List_destroy and displayed with List_display. The list is traversed using List_getNext and List_hasNext. Elements are added at the current position with List_insert and removed with List_remove. Additionally, a node is added at the end of the list with List_insertTail and at the beginning with List_insertHead. Nodes are removed from the head of the list with List_removeHead and from the end of the list with List_removeTail. As the list keeps track of the current node during traversal (changed with List_getNext) it is rewinded with List_rewind. The function List_isEmpty returns BOOLEAN_TRUE if the list is empty and BOOLEAN_FALSE otherwise.

The structure List provides also a possibility to store a name for this list as a char*. The name can be accessed with List_setName and List_getName. The structure keeps automatically track of the current number of nodes. This value is returned by List_getNumberOfNodes.
Stacks are implemented by the define functions List_pushhead, List_pophead and List_top. Functionality of a queue is provided by List_enqueue and List_dequeue.

One has to provide a function pointer to display the data that is stored in the individual nodes via the void*! The display function has to comply to the prototype void displayFunction( void*, FILE* ). A function pointer to destroy (i.e. free) the data of a node is also mandatory. The destroy function has to comply to the prototype void destroyFunction ( void* ).

The list can automatically check for every insertion operation if there exists already a node with a void* data that is identical to the one that should be inserted. This has to be specified with a function parameter during creation of the List (List_create) and cannot be changed afterwards. However, function List_getUniqueData can be used to query a list about its 'uniqueness' status. The status is queried with List_getUniqueData. Uniqueness is guaranteed with the function identicalFunction; it is provided as a function parameter to List_create. The provided function identicalFunction has to return BOOLEAN_FALSE or BOOLEAN_TRUE if the data is identical or non-identical, respectively.

Structure listNode

The structure listNode consists of a void* to store the data, of a pointer to the next node in the list and of a pointer to the previous node (self-referential structure).

Description of the members of listNode:

void* - points to the data of the node
struct listNode* - pointer on the previous node in the list
struct listNode* - pointer on the next node in the list

Structure List

The structure List conists of a ListNode_Ptr on the first node, a ListNode_Ptr on the last node, a pointer on the current node (needed for sequential traversal of the list) and a function pointer to display the data of a node. Additionally, a name (char*) and the current number of nodes is stored and accessible with appropriate functions.

Description of the members of SingleLinkedList:

name - char* to store the name of the list
numberOfNodes - stores the number of nodes in the list
headNodePtr - ListNode_Ptr on the first node in the list
tailNodePtr - ListNode_Ptr on the last node in the list
currentNodePtr - ListNode_Ptr on the current node in the list
uniqueData - indicates via BOOLEAN_TRUE and BOOLEAN_FALSE if nodes with identical data are allowed
displayFunction - pointer to a function that is capable of displaying the data of a node
destroyFunction - pointer to a function that is capable of destroying the data of a node
identicalFunction - pointer to a function that returns whether the data of two nodes is identical

Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - added support for lists that contain only non-identical data in their nodes (added member uniqueData and identicalFunction to structure List; added functions List_isContained, List_getUniqueData; modified List_insert, List_insertHead and List_insertTail); the currentNodePtr

04/12/2003 - Uli Fechner - changed the behaviour of re-setting currentNodePtr in List_remove and List_removeHead for consistency reasons \code

Definition in file doubleLinkedList.c.


Define Documentation

#define BOOLEAN_FALSE   0
 

Boolean variables are simulated with the defines BOOLEAN_FALSE and BOOLEAN_TRUE.

Author:
Uli Fechner
Version:
03/12/2003 - Uli Fechner - initial release

Definition at line 141 of file doubleLinkedList.c.

Referenced by DoubleArray_calculateMeanAndSd(), DoubleArray_lessThan(), enqueueMolecules(), filterMolecules(), GivenClp_create(), List_hasNext(), List_insert(), List_insertHead(), List_insertTail(), List_isContained(), List_isEmpty(), main(), parseClp(), readDataFromStream(), SmilesCompound_create(), SmilesCompound_identical(), and SmilesCompound_setSmiles().

#define BOOLEAN_TRUE   1
 

Boolean variables are simulated with the defines BOOLEAN_FALSE and BOOLEAN_TRUE.

Author:
Uli Fechner
Version:
03/12/2003 - Uli Fechner - initial release

Definition at line 150 of file doubleLinkedList.c.

Referenced by DoubleArray_calculateMeanAndSd(), DoubleArray_lessThan(), filterMolecules(), List_hasNext(), List_insert(), List_insertHead(), List_insertTail(), List_isContained(), List_isEmpty(), main(), parseClp(), SmilesCompound_identical(), and SmilesCompound_setSmiles().

#define DOUBLELINKEDLIST_DATE   "04-Dec-2003"
 

Definition at line 3 of file doubleLinkedList.c.

Referenced by displayVersionInformation().

#define DOUBLELINKEDLIST_DEBUG   0
 

If DOUBLELINKESLIST_DEBUG is set to 1 some debug information is written to standard error.

Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 132 of file doubleLinkedList.c.

#define DOUBLELINKEDLIST_VERSION   "1.1.1"
 

Definition at line 2 of file doubleLinkedList.c.

Referenced by displayVersionInformation().

#define List_dequeue listPtr   )     ( List_removeHead( listPtr ) )
 

Dequeues an element of a queue.

Attention:
This define is only a wrapper for List_removeTail!
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 211 of file doubleLinkedList.c.

#define List_enqueue listPtr,
data   )     ( List_insertTail( listPtr, data ) )
 

Enqueues an element in a queue.

Attention:
This define is only a wrapper for List_insertTail!
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 200 of file doubleLinkedList.c.

#define List_pophead listPtr   )     ( List_removeHead( listPtr ) )
 

Pops an element from top of a stack.

Attention:
This define is only a wrapper for List_removeHead!
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 175 of file doubleLinkedList.c.

#define List_pushhead listPtr,
data   )     ( List_insertHead( listPtr, data ) )
 

Pushes an element on top of a stack.

Attention:
This define is only a wrapper for List_insertHead!
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 164 of file doubleLinkedList.c.

#define List_top listPtr   ) 
 

Value:

( ( List_rewind( listPtr ) ), \
        ( List_getNext( listPtr ) ) )
Returns the element on top of a stack without removing it.

Attention:
This define wraps sequentially List_rewind and List_getNext!
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 186 of file doubleLinkedList.c.


Typedef Documentation

typedef List* List_Ptr
 

A pointer to structure List is assigned the name List_Ptr.

Definition at line 121 of file doubleLinkedList.c.

Referenced by enqueueMolecules(), filterMolecules(), List_create(), main(), readDataFromFile(), and readDataFromStream().

typedef struct listNode ListNode
 

A structure listNode is assigned the name ListNode.

Definition at line 102 of file doubleLinkedList.c.

Referenced by List_insert(), List_insertHead(), and List_insertTail().

typedef ListNode* ListNode_Ptr
 

A pointer to structure ListNode is assigned the name ListNode_Ptr.

Definition at line 105 of file doubleLinkedList.c.

Referenced by List_display(), List_insert(), List_insertHead(), List_insertTail(), List_isContained(), List_remove(), List_removeHead(), and List_removeTail().


Function Documentation

List_Ptr List_create const int  uniqueData,
void(*  displayFunction)(void *data, FILE *outputStream),
\void(*  destroyFunction)(void *data),
\int(*  identicalFunction)(const void *data1, const void *data2)
 

Creates an List structure.

A structure List is created. The memory of the structure itself and of its members is allocated automatically. A function pointer on a function to display the data that is stored in this List has to provided as an argument.

Parameters:
uniqueData indicates via a boolean variable whether the data of the list should be checked for uniqueness
displayFunction function pointer on a function that is capable of displaying the data of a node
destroyFunction function pointer on a function that is capable of destroying the data of a node
identicalFunction function pointer on a function that is capable of checking whether the data of two nodes is identical
Return values:
List_Ptr pointer on the newly created structure List
Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - added function parameters uniqueData and compareFunction

Definition at line 271 of file doubleLinkedList.c.

References AbortProgram, List::currentNodePtr, List::destroyFunction, List::displayFunction, List::headNodePtr, List::identicalFunction, List_Ptr, MemoryError, List::name, List::numberOfNodes, List::tailNodePtr, and List::uniqueData.

Referenced by readDataFromStream().

void List_destroy List_Ptr  listPtr  ) 
 

Destroys a List structure.

The structure List the pointer listPtr refers to is destroyed. The memory of the structure itself and of its members is freed automatically.

Attention:
The data of all nodes is freed with a trivial free of the node void pointers! If the void pointer refers to structures that have members that allocate memory this memory is not freed! In such a case it is best to remove the nodes one by one and free the memory individually.
Parameters:
listPtr pointer on structure List that should be destroyed
Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

Definition at line 320 of file doubleLinkedList.c.

References AbortProgram, List::destroyFunction, List_isEmpty(), List_removeHead(), and List_rewind().

Referenced by main().

void List_display const List_Ptr  listPtr,
FILE *  outputStream
 

Displays a structure List.

The structure List the pointer listPtr refers to is displayed on the FILE* outputStream. If the list is empty an appropriate message is printed on outputStream.

Parameters:
listPtr pointer on the structure List that should be displayed
outputStream FILE* on the stream the output should be sent to
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - added support for the members uniqueData and identicalFunction

Definition at line 352 of file doubleLinkedList.c.

References List::currentNodePtr, listNode::data, List::destroyFunction, List::displayFunction, List::headNodePtr, List::identicalFunction, ListNode_Ptr, List::name, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, List::tailNodePtr, and List::uniqueData.

Referenced by main().

char * List_getName const List_Ptr  listPtr  ) 
 

The name of the List is returned.

Parameters:
listPtr pointer on the structure List that contains the value
Return values:
char name of the List
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 848 of file doubleLinkedList.c.

References List::name.

Referenced by List_getNext(), and List_remove().

void * List_getNext const List_Ptr  listPtr  ) 
 

Returns the data of the next node in the list.

The current position within the List is stored in the member currentNodePtr.

Parameters:
listPtr pointer on the structure List the node belongs to
Return values:
void* on the data of the node
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 391 of file doubleLinkedList.c.

References AbortProgram, List::currentNodePtr, listNode::data, List::headNodePtr, List_getName(), List_isEmpty(), listNode::nextNodePtr, and List::tailNodePtr.

Referenced by main().

int List_getNumberOfNodes const List_Ptr  listPtr  ) 
 

The numberOfNodes of the List is returned.

Parameters:
listPtr pointer on the structure List
Return values:
int number of nodes in the List
Author:
Uli Fechner
Version:
25/11/2003 - Uli Fechner - initial release

Definition at line 813 of file doubleLinkedList.c.

References List::numberOfNodes.

Referenced by main().

int List_getUniqueData const List_Ptr  listPtr  ) 
 

The value of the member uniqueData of the List is returned.

Parameters:
listPtr pointer on the structure List that contains the value
Return values:
int value of uniqueData of the List
Author:
Uli Fechner
Version:
03/12/2003 - Uli Fechner - initial release

Definition at line 860 of file doubleLinkedList.c.

References List::uniqueData.

int List_hasNext const List_Ptr  listPtr  ) 
 

Checks if the List has at least one more node (directed forwards).

The current position within the List is stored in the member currentNodePtr. This function checks if currentNodePtr points to tailNodePtr. If so, the end of the list is reached.

Parameters:
listPtr pointer on the structure List that is checked
Return values:
int BOOLEAN_FALSE or BOOLEAN_TRUE
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 436 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, List::currentNodePtr, and List::tailNodePtr.

Referenced by main().

int List_insert const List_Ptr  listPtr,
void *  data
 

A new node is inserted in List at the position that is referred by currentNodePtr.

Attention:
After a successful insertion the currentNodePtr points to the newly created node.
Parameters:
listPtr pointer on the structure List the node is inserted
data data of the new node
Return values:
int returns BOOLEAN_TRUE on a successful and BOOLEAN_FALSE on a unsuccessful insertion
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - changed return type from void to int (BOOLEAN_TRUE and BOOLEAN_FALSE); added support for uniqueData list

Definition at line 472 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, List::currentNodePtr, listNode::data, List::headNodePtr, List_insertHead(), List_insertTail(), List_isContained(), ListNode, ListNode_Ptr, MemoryError, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, List::tailNodePtr, and List::uniqueData.

int List_insertHead const List_Ptr  listPtr,
void *  data
 

Inserts a node at the head of the List.

Attention:
The currentNodePtr is not changed if this function is called directly.
Parameters:
listPtr pointer on the structure List the new node is added
data void pointer on the actual data
Return values:
int returns BOOLEAN_TRUE on a successful and BOOLEAN_FALSE on an unsuccessful insertion
Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - changed return type from void to int (BOOLEAN_TRUE and BOOLEAN_FALSE); added support for uniqueData list

Definition at line 578 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, listNode::data, List::headNodePtr, List_isContained(), ListNode, ListNode_Ptr, MemoryError, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, List::tailNodePtr, and List::uniqueData.

Referenced by List_insert().

int List_insertTail const List_Ptr  listPtr,
void *  data
 

Inserts a node at the tail of the List.

Attention:
The currentNodePtr is not changed if this function is called directly.
Parameters:
listPtr pointer on the structure List the new node is added
data void pointer on the actual data
Return values:
int returns BOOLEAN_TRUE on a successful and BOOLEAN_FALSE on an unsuccessful insertion
Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

03/12/2003 - Uli Fechner - changed return type from void to int (BOOLEAN_TRUE and BOOLEAN_FALSE); added support for uniqueData list

Definition at line 631 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, listNode::data, List::headNodePtr, List_isContained(), ListNode, ListNode_Ptr, MemoryError, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, List::tailNodePtr, and List::uniqueData.

Referenced by enqueueMolecules(), List_insert(), and readDataFromStream().

int List_isContained const List_Ptr  listPtr,
const void *  data
 

Checks if data is contained in the List.

This function returns BOOLEAN_TRUE if data is contained in the List and BOOLEAN_FALSE otherwise.

Parameters:
listPtr pointer on the structure List that is checked for the presence of data
data void pointer on the actual data
Return values:
int BOOLEAN_TRUE or BOOLEAN_FALSE
Author:
Uli Fechner
Version:
03/12/2003 - Uli Fechner - initial release

Definition at line 789 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, listNode::data, List::headNodePtr, List::identicalFunction, ListNode_Ptr, and listNode::nextNodePtr.

Referenced by filterMolecules(), List_insert(), List_insertHead(), and List_insertTail().

int List_isEmpty const List_Ptr  listPtr  ) 
 

Checks if the structure List is empty.

This function returns BOOLEAN_TRUE if the structure List is empty and BOOLEAN_FALSE otherwise.

Parameters:
listPtr pointer on the structure List that is checked for emptiness
Return values:
int BOOLEAN_TRUE or BOOLEAN_FALSE
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 770 of file doubleLinkedList.c.

References BOOLEAN_FALSE, BOOLEAN_TRUE, and List::headNodePtr.

Referenced by List_destroy(), and List_getNext().

void * List_remove const List_Ptr  listPtr  ) 
 

The node that is referred to by currentNodePtr is removed from List and its data is returned.

Attention:
The currentNodePtr is moved to the previous node. If the head node is removed currentNodePtr is moved before the new head node. This behaviour guarantees that the following call of List_getNext returns the element that follows the one that was removed.
Parameters:
listPtr pointer on the structure List the node is removed from
Return values:
void* data of the removed node
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

04/12/2003 - Uli Fechner - changed the behaviour of currentNodePtr

Definition at line 531 of file doubleLinkedList.c.

References AbortProgram, List::currentNodePtr, listNode::data, List::headNodePtr, List_getName(), List_removeHead(), List_removeTail(), ListNode_Ptr, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, and List::tailNodePtr.

Referenced by main().

void * List_removeHead const List_Ptr  listPtr  ) 
 

The first node of the structure List is removed.

Attention:
If the currentNodePtr points to the head node it is moved before the new head node. Otherwise it is left untouched. This behaviour guarantees that a call to List_getNext retrieves the node that follows the one that was removed.
Parameters:
listPtr pointer on the structure List the node is removed from
Return values:
void* data of the removed node
Author:
Uli Fechner
Version:
28/11/2003 - Uli Fechner - initial release

04/12/2003 - Uli Fechner - changed the behaviour of the currentNodePtr

Definition at line 684 of file doubleLinkedList.c.

References AbortProgram, List::currentNodePtr, listNode::data, List::headNodePtr, ListNode_Ptr, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, and List::tailNodePtr.

Referenced by List_destroy(), and List_remove().

void * List_removeTail const List_Ptr  listPtr  ) 
 

The last node of the structure List is removed.

Attention:
If the currentNodePtr points to the tail node it is moved to the new tail node. Otherwise it is left untouched.
Parameters:
listPtr pointer on the structure List the node is removed from
Return values:
void* data of the removed node
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 728 of file doubleLinkedList.c.

References AbortProgram, List::currentNodePtr, listNode::data, List::headNodePtr, ListNode_Ptr, listNode::nextNodePtr, List::numberOfNodes, listNode::previousNodePtr, and List::tailNodePtr.

Referenced by List_remove().

void List_rewind const List_Ptr  listPtr  ) 
 

Re-sets the position pointer of the List to the beginning of the list.

The current position within the List is stored in the member currentNodePtr. This function re-sets currentNodePtr to the very beginning of the list, so that the next call to List_getNext returns the data of the first node.

Parameters:
listPtr pointer on the structure List the position pointer is re-set
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 454 of file doubleLinkedList.c.

References List::currentNodePtr.

Referenced by List_destroy(), and main().

void List_setName const List_Ptr  listPtr,
char *  name
 

Sets the name of the List.

Attention:
The provided parameter name is copied. name is not freed afterwards. This has to be done by the caller of this function!
Parameters:
listPtr pointer on the structure List that is associated with name
name name of the List
Author:
Uli Fechner
Version:
24/11/2003 - Uli Fechner - initial release

Definition at line 829 of file doubleLinkedList.c.

References MemoryError, and List::name.

Referenced by main().


Generated on Tue Nov 9 16:27:12 2004 for retroflux by doxygen 1.3.6