slist.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_SListIterator
	Definition of a SListIterator. More...

Macros
#define	SLIST_NULL   ((void *) 0)
	A null SListValue. More...

Typedefs
typedef struct _SListEntry	SListEntry
	Represents an entry in a singly-linked list. More...
typedef struct _SListIterator	SListIterator
	Structure used to iterate over a list. More...
typedef void *	SListValue
	Value stored in a list. More...
typedef int(*	SListCompareFunc) (SListValue value1, SListValue value2)
	Callback function used to compare values in a list when sorting. More...
typedef int(*	SListEqualFunc) (SListValue value1, SListValue value2)
	Callback function used to determine of two values in a list are equal. More...

Functions
void	slist_free (SListEntry *list)
	Free an entire list. More...
SListEntry *	slist_prepend (SListEntry **list, SListValue data)
	Prepend a value to the start of a list. More...
SListEntry *	slist_append (SListEntry **list, SListValue data)
	Append a value to the end of a list. More...
SListEntry *	slist_next (SListEntry *listentry)
	Retrieve the next entry in a list. More...
SListValue	slist_data (SListEntry *listentry)
	Retrieve the value stored at a list entry. More...
SListEntry *	slist_nth_entry (SListEntry *list, int n)
	Retrieve the entry at a specified index in a list. More...
SListValue	slist_nth_data (SListEntry *list, int n)
	Retrieve the value stored at a specified index in the list. More...
int	slist_length (SListEntry *list)
	Find the length of a list. More...
SListValue *	slist_to_array (SListEntry *list)
	Create a C array containing the contents of a list. More...
int	slist_remove_entry (SListEntry **list, SListEntry *entry)
	Remove an entry from a list. More...
int	slist_remove_data (SListEntry **list, SListEqualFunc callback, SListValue data)
	Remove all occurrences of a particular value from a list. More...
void	slist_sort (SListEntry **list, SListCompareFunc compare_func)
	Sort a list. More...
SListEntry *	slist_find_data (SListEntry *list, SListEqualFunc callback, SListValue data)
	Find the entry for a particular value in a list. More...
void	slist_iterate (SListEntry **list, SListIterator *iter)
	Initialise a SListIterator structure to iterate over a list. More...
int	slist_iter_has_more (SListIterator *iterator)
	Determine if there are more values in the list to iterate over. More...
SListValue	slist_iter_next (SListIterator *iterator)
	Using a list iterator, retrieve the next value from the list. More...
void	slist_iter_remove (SListIterator *iterator)
	Delete the current entry in the list (the value last returned from slist_iter_next) More...

Detailed Description

Singly-linked list.

A singly-linked list stores a collection of values. Each entry in the list (represented by a pointer to a SListEntry structure) contains a link to the next entry. It is only possible to iterate over entries in a singly linked list in one direction.

To create a new singly-linked list, create a variable which is a pointer to a SListEntry, and initialise it to NULL.

To destroy a singly linked list, use slist_free.

To add a new value at the start of a list, use slist_prepend. To add a new value at the end of a list, use slist_append.

To find the length of a list, use slist_length.

To access a value in a list by its index in the list, use slist_nth_data.

To search a list for a value, use slist_find_data.

To sort a list into an order, use slist_sort.

To find a particular entry in a list by its index, use slist_nth_entry.

To iterate over each value in a list, use slist_iterate to initialise a SListIterator structure, with slist_iter_next and slist_iter_has_more to retrieve each value in turn. slist_iter_remove can be used to efficiently remove the current entry from the list.

Given a particular entry in a list (SListEntry):

• To find the next entry, use slist_next.
• To access the value stored at the entry, use slist_data.
• To remove the entry, use slist_remove_entry.

Definition in file slist.h.

Macro Definition Documentation

SLIST_NULL

#define SLIST_NULL   ((void *) 0)

A null SListValue.

Definition at line 108 of file slist.h.

Typedef Documentation

SListCompareFunc

typedef int(* SListCompareFunc) (SListValue value1, SListValue value2)

Callback function used to compare values in a list when sorting.

Returns

A negative value if value1 should be sorted before value2, a positive value if value1 should be sorted after value2, zero if value1 and value2 are equal.

Definition at line 117 of file slist.h.

SListEntry

typedef struct _SListEntry SListEntry

Represents an entry in a singly-linked list.

The empty list is represented by a NULL pointer. To initialise a new singly linked list, simply create a variable of this type containing a pointer to NULL.

Definition at line 1 of file slist.h.

SListEqualFunc

typedef int(* SListEqualFunc) (SListValue value1, SListValue value2)

Callback function used to determine of two values in a list are equal.

Returns

A non-zero value if value1 and value2 are equal, zero if they are not equal.

Definition at line 127 of file slist.h.

SListIterator

typedef struct _SListIterator SListIterator

Structure used to iterate over a list.

Definition at line 1 of file slist.h.

SListValue

typedef void* SListValue

Value stored in a list.

Definition at line 92 of file slist.h.

Function Documentation

slist_append()

SListEntry* slist_append	(	SListEntry **	list,
		SListValue	data
	)

Append a value to the end of a list.

Parameters

list	Pointer to the list to append to.
data	The value to append.

Returns

The new entry in the list, or NULL if it was not possible to allocate a new entry.

slist_data()

SListValue slist_data

(

SListEntry *

listentry

)

Retrieve the value stored at a list entry.

Parameters

listentry

Pointer to the list entry.

Returns

The value at the list entry.

slist_find_data()

SListEntry* slist_find_data	(	SListEntry *	list,
		SListEqualFunc	callback,
		SListValue	data
	)

Find the entry for a particular value in a list.

Parameters

list	The list to search.
callback	Callback function to be invoked to determine if values in the list are equal to the value to be searched for.
data	The value to search for.

Returns

The list entry of the value being searched for, or NULL if not found.

slist_free()

void slist_free

(

SListEntry *

list

)

Free an entire list.

Parameters

list	The list to free.

slist_iter_has_more()

int slist_iter_has_more

(

SListIterator *

iterator

)

Determine if there are more values in the list to iterate over.

Parameters

iterator

The list iterator.

Returns

Zero if there are no more values in the list to iterate over, non-zero if there are more values to read.

slist_iter_next()

SListValue slist_iter_next

(

SListIterator *

iterator

)

Using a list iterator, retrieve the next value from the list.

Parameters

iterator

The list iterator.

Returns

The next value from the list, or SLIST_NULL if there are no more values in the list.

slist_iter_remove()

void slist_iter_remove

(

SListIterator *

iterator

)

Delete the current entry in the list (the value last returned from slist_iter_next)

Parameters

iterator

The list iterator.

slist_iterate()

void slist_iterate	(	SListEntry **	list,
		SListIterator *	iter
	)

Initialise a SListIterator structure to iterate over a list.

Parameters

list	Pointer to the list to iterate over.
iter	Pointer to a SListIterator structure to initialise.

slist_length()

int slist_length

(

SListEntry *

list

)

Find the length of a list.

Parameters

list

The list.

Returns

The number of entries in the list.

slist_next()

SListEntry* slist_next

(

SListEntry *

listentry

)

Retrieve the next entry in a list.

Parameters

listentry

Pointer to the list entry.

Returns

The next entry in the list.

slist_nth_data()

SListValue slist_nth_data	(	SListEntry *	list,
		int	n
	)

Retrieve the value stored at a specified index in the list.

Parameters

list	The list.
n	The index into the list.

Returns

The value stored at the specified index, or SLIST_NULL if unsuccessful.

slist_nth_entry()

SListEntry* slist_nth_entry	(	SListEntry *	list,
		int	n
	)

Retrieve the entry at a specified index in a list.

Parameters

list	The list.
n	The index into the list .

Returns

The entry at the specified index, or NULL if out of range.

slist_prepend()

SListEntry* slist_prepend	(	SListEntry **	list,
		SListValue	data
	)

Prepend a value to the start of a list.

Parameters

list	Pointer to the list to prepend to.
data	The value to prepend.

Returns

The new entry in the list, or NULL if it was not possible to allocate a new entry.

slist_remove_data()

int slist_remove_data	(	SListEntry **	list,
		SListEqualFunc	callback,
		SListValue	data
	)

Remove all occurrences of a particular value from a list.

Parameters

list	Pointer to the list.
callback	Callback function to invoke to compare values in the list with the value to remove.
data	The value to remove from the list.

Returns

The number of entries removed from the list.

slist_remove_entry()

int slist_remove_entry	(	SListEntry **	list,
		SListEntry *	entry
	)

Remove an entry from a list.

Parameters

list	Pointer to the list.
entry	The list entry to remove.

Returns

If the entry is not found in the list, returns zero, else returns non-zero.

slist_sort()

void slist_sort	(	SListEntry **	list,
		SListCompareFunc	compare_func
	)

Sort a list.

Parameters

list	Pointer to the list to sort.
compare_func	Function used to compare values in the list.

slist_to_array()

SListValue* slist_to_array

(

SListEntry *

list

)

Create a C array containing the contents of a list.

Parameters

list

The list.

Returns

A newly-allocated C array containing all values in the list, or NULL if it was not possible to allocate the memory for the array. The length of the array is equal to the length of the list (see slist_length).