Doubly-linked list. More...

#include "mercury_util_config.h"

Include dependency graph for mercury_list.h:

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

Classes
struct	hg_list_iter
	Definition of a hg_list_iter_t. More...

Macros
#define	HG_LIST_NULL ((void *) 0)
	A null hg_list_value_t. More...

Typedefs
typedef struct hg_list_entry	hg_list_entry_t
	Represents an entry in a doubly-linked list. More...

typedef struct hg_list_iter	hg_list_iter_t
	Structure used to iterate over a list. More...

typedef void *	hg_list_value_t
	A value stored in a list. More...

typedef int(*	hg_list_compare_func_t )(hg_list_value_t value1, hg_list_value_t value2)
	Callback function used to compare values in a list when sorting. More...

typedef int(*	hg_list_equal_func_t )(hg_list_value_t value1, hg_list_value_t value2)
	Callback function used to determine of two values in a list are equal. More...

Functions
HG_UTIL_EXPORT void	hg_list_free (hg_list_entry_t *list)
	Free an entire list. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_prepend (hg_list_entry_t **list, hg_list_value_t data)
	Prepend a value to the start of a list. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_append (hg_list_entry_t **list, hg_list_value_t data)
	Append a value to the end of a list. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_prev (hg_list_entry_t *listentry)
	Retrieve the previous entry in a list. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_next (hg_list_entry_t *listentry)
	Retrieve the next entry in a list. More...

HG_UTIL_EXPORT hg_list_value_t	hg_list_data (hg_list_entry_t *listentry)
	Retrieve the value at a list entry. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_nth_entry (hg_list_entry_t *list, unsigned int n)
	Retrieve the entry at a specified index in a list. More...

HG_UTIL_EXPORT hg_list_value_t	hg_list_nth_data (hg_list_entry_t *list, unsigned int n)
	Retrieve the value at a specified index in the list. More...

HG_UTIL_EXPORT unsigned int	hg_list_length (hg_list_entry_t *list)
	Find the length of a list. More...

HG_UTIL_EXPORT hg_list_value_t *	hg_list_to_array (hg_list_entry_t *list)
	Create a C array containing the contents of a list. More...

HG_UTIL_EXPORT int	hg_list_remove_entry (hg_list_entry_t *list, hg_list_entry_t entry)
	Remove an entry from a list. More...

HG_UTIL_EXPORT unsigned int	hg_list_remove_data (hg_list_entry_t **list, hg_list_equal_func_t callback, hg_list_value_t data)
	Remove all occurrences of a particular value from a list. More...

HG_UTIL_EXPORT void	hg_list_sort (hg_list_entry_t **list, hg_list_compare_func_t compare_func)
	Sort a list. More...

HG_UTIL_EXPORT hg_list_entry_t *	hg_list_find_data (hg_list_entry_t *list, hg_list_equal_func_t callback, hg_list_value_t data)
	Find the entry for a particular value in a list. More...

HG_UTIL_EXPORT void	hg_list_iterate (hg_list_entry_t *list, hg_list_iter_t iter)
	Initialize a hg_list_iter_t structure to iterate over a list. More...

HG_UTIL_EXPORT int	hg_list_iter_has_more (hg_list_iter_t *iterator)
	Determine if there are more values in the list to iterate over. More...

HG_UTIL_EXPORT hg_list_value_t	hg_list_iter_next (hg_list_iter_t *iterator)
	Using a list iterator, retrieve the next value from the list. More...

HG_UTIL_EXPORT void	hg_list_iter_remove (hg_list_iter_t *iterator)
	Delete the current entry in the list (the value last returned from list_iter_next) More...

Detailed Description

Doubly-linked list.

A doubly-linked list stores a collection of values. Each entry in the list (represented by a pointer a hg_list_entry_t structure) contains a link to the next entry and the previous entry. It is therefore possible to iterate over entries in the list in either direction.

To create an empty list, create a new variable which is a pointer to a hg_list_entry_t structure, and initialize it to NULL. To destroy an entire list, use list_free.

To add a value to a list, use list_append or list_prepend.

To remove a value from a list, use list_remove_entry or list_remove_data.

To iterate over entries in a list, use list_iterate to initialize a hg_list_iter_t structure, with list_iter_next and list_iter_has_more to retrieve each value in turn. list_iter_remove can be used to remove the current entry.

To access an entry in the list by index, use list_nth_entry or list_nth_data.

To sort a list, use list_sort.

Definition in file mercury_list.h.

Macro Definition Documentation

#define HG_LIST_NULL ((void *) 0)

A null hg_list_value_t.

Definition at line 95 of file mercury_list.h.

Typedef Documentation

typedef struct hg_list_entry hg_list_entry_t

Represents an entry in a doubly-linked list.

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

Definition at line 68 of file mercury_list.h.

typedef struct hg_list_iter hg_list_iter_t

Structure used to iterate over a list.

Definition at line 74 of file mercury_list.h.

typedef void* hg_list_value_t

A value stored in a list.

Definition at line 80 of file mercury_list.h.

typedef int(* hg_list_compare_func_t)(hg_list_value_t value1, hg_list_value_t value2)

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

Parameters

value1	The first value to compare.
value2	The second value to compare.

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 107 of file mercury_list.h.

typedef int(* hg_list_equal_func_t)(hg_list_value_t value1, hg_list_value_t value2)

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

Parameters

value1	The first value to compare.
value2	The second value to compare.

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

Definition at line 119 of file mercury_list.h.

Function Documentation

HG_UTIL_EXPORT void hg_list_free ( hg_list_entry_t * list )

Free an entire list.

Parameters

list	The list to free.

HG_UTIL_EXPORT hg_list_entry_t* hg_list_prepend	(	hg_list_entry_t **	list,
		hg_list_value_t	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 the memory for the new entry.

HG_UTIL_EXPORT hg_list_entry_t* hg_list_append	(	hg_list_entry_t **	list,
		hg_list_value_t	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 the memory for the new entry.

HG_UTIL_EXPORT hg_list_entry_t* hg_list_prev ( hg_list_entry_t * listentry )

Retrieve the previous entry in a list.

Parameters

listentry Pointer to the list entry.

Returns: The previous entry in the list, or NULL if this was the first entry in the list.

HG_UTIL_EXPORT hg_list_entry_t* hg_list_next ( hg_list_entry_t * listentry )

Retrieve the next entry in a list.

Parameters

listentry Pointer to the list entry.

Returns: The next entry in the list, or NULL if this was the last entry in the list.

HG_UTIL_EXPORT hg_list_value_t hg_list_data ( hg_list_entry_t * listentry )

Retrieve the value at a list entry.

Parameters

listentry Pointer to the list entry.

Returns: The value stored at the list entry.

HG_UTIL_EXPORT hg_list_entry_t* hg_list_nth_entry	(	hg_list_entry_t *	list,
		unsigned 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.

HG_UTIL_EXPORT hg_list_value_t hg_list_nth_data	(	hg_list_entry_t *	list,
		unsigned int	n
	)

Retrieve the value at a specified index in the list.

Parameters

list	The list.
n	The index into the list.

Returns: The value at the specified index, or HG_LIST_NULL if unsuccessful.

HG_UTIL_EXPORT unsigned int hg_list_length ( hg_list_entry_t * list )

Find the length of a list.

Parameters

list The list.

Returns: The number of entries in the list.

HG_UTIL_EXPORT hg_list_value_t* hg_list_to_array ( hg_list_entry_t * 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. The length of the array is equal to the length of the list (see list_length).

HG_UTIL_EXPORT int hg_list_remove_entry	(	hg_list_entry_t **	list,
		hg_list_entry_t *	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.

HG_UTIL_EXPORT unsigned int hg_list_remove_data	(	hg_list_entry_t **	list,
		hg_list_equal_func_t	callback,
		hg_list_value_t	data
	)

Remove all occurrences of a particular value from a list.

Parameters

list	Pointer to the list.
callback	Function to invoke to compare values in the list with the value to be removed.
data	The value to remove from the list.

Returns: The number of entries removed from the list.

HG_UTIL_EXPORT void hg_list_sort	(	hg_list_entry_t **	list,
		hg_list_compare_func_t	compare_func
	)

Sort a list.

Parameters

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

HG_UTIL_EXPORT hg_list_entry_t* hg_list_find_data	(	hg_list_entry_t *	list,
		hg_list_equal_func_t	callback,
		hg_list_value_t	data
	)

Find the entry for a particular value in a list.

Parameters

list	The list to search.
callback	Function to invoke to compare values in the list with the value to be searched for.
data	The value to search for.

Returns: The list entry of the item being searched for, or NULL if not found.

HG_UTIL_EXPORT void hg_list_iterate	(	hg_list_entry_t **	list,
		hg_list_iter_t *	iter
	)

Initialize a hg_list_iter_t structure to iterate over a list.

Parameters

list	A pointer to the list to iterate over.
iter	A pointer to an iterator structure to initialize.

HG_UTIL_EXPORT int hg_list_iter_has_more ( hg_list_iter_t * 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.

HG_UTIL_EXPORT hg_list_value_t hg_list_iter_next ( hg_list_iter_t * 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 HG_LIST_NULL if there are no more values in the list.

HG_UTIL_EXPORT void hg_list_iter_remove ( hg_list_iter_t * iterator )

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

Parameters

iterator The list iterator.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation