List.h

Abstract

Simple Linked-List implementation

Discussion

Each item is a void*, giving the flexability to use any data time. When the list is destroyed, each item is free()d.

(C)2001-2003 Stewart Smith

Distributed under the GNU Public License

See the included LICENSE file for details

Functions

list_append

int list_append (
    List *theList,
    void* theItem
);

Parameters

Name Description

*theList pointer to the list to add the item to

*theItem pointer to void, the item to append.

Name	Description
`*theList`	pointer to the list to add the item to
`*theItem`	pointer to void, the item to append.

Result: true on success

list_destroy

Abstract: Removes all items from a list.

void list_destroy (
    List *theList
);

Will traverse all nodes in a list, first free()ing the item, and then removing the node.

list_getID

void *list_getID (
    List *theList,
    long id
);

Parameters

Name Description

theList pointer to list to search

id number of items to traverse into the list (from start)

Name	Description
`theList`	pointer to list to search
`id`	number of items to traverse into the list (from start)

Result: pointer to item

list_getItem

Abstract: Get an item from the list

void *list_getItem (
    List *theList,
    void* item,
    int (*compare
)(void*,void*));

Parameters

Name Description

theList pointer to list to search

item item to look for (void*)

compare pointer to function to compare item to each node's item. They can be different types, but the compare function must be able to track this itself.

Name	Description
`theList`	pointer to list to search
`item`	item to look for (void*)
`compare`	pointer to function to compare item to each node's item. They can be different types, but the compare function must be able to track this itself.

Result: pointer to item

list_new

int list_new (
    List *theList
);

Parameters

Name Description

*theList pointer to list to be 'newed'

Name	Description
`*theList`	pointer to list to be 'newed'

Result: integer, true on success

list_traverse

void* list_traverse (
    List *theList,
    ListNode** current
);

Parameters

Name Description

theList list to traverse

current Status variable (initially should be NULL)

Name	Description
`theList`	list to traverse
`current`	Status variable (initially should be NULL)

Result: next item in list

Typedefs

List

Abstract: Linked List

typedef struct {
  ListNode* list;
  ListNode* current;
  void (*freeItem)(void*);
  int numItems; 
} List;

Type for a linked list. Before use, list_new(*List) must be called to initialise the structure.

Fields

Name Description

list Pointer to first ListNode in the list

current pointer to current node in traversal

freeItem Pointer to function (void freeItem(void*)) used to free a node, otherwise NULL.

numItems number of items in the list.

Name	Description
`list`	Pointer to first ListNode in the list
`current`	pointer to current node in traversal
`freeItem`	Pointer to function (void freeItem(void*)) used to free a node, otherwise NULL.
`numItems`	number of items in the list.

ListNode

Abstract: Defines ListNode as the struct ListNodeStruc

typedef struct ListNodeStruc ListNode;

Structs

ListNodeStruc

Abstract: Structure for a List Node

struct ListNodeStruc{
  void *item;
  struct ListNodeStruc *next;
};

Fields

Name Description

item Pointer to List item. Should be malloc()ed externally to the list, as it is free()ed when list_destroy is called.

next pointer to the next ListNode, or NULL if last node.

Name	Description
`item`	Pointer to List item. Should be malloc()ed externally to the list, as it is free()ed when list_destroy is called.
`next`	pointer to the next ListNode, or NULL if last node.

(Last Updated 4/21/2003)