List functions

Data Structures and functions for manipulating linked-lists. More...

Data Structures
struct	_GGZListEntry
	A single entry in a GGZList. More...
struct	_GGZList
	Simple doubly-linked list. More...
Defines
#define	GGZ_LIST_REPLACE_DUPS   0x00
	Overwrite duplicate values on insert.
#define	GGZ_LIST_ALLOW_DUPS   0x01
	Allow duplicate data entries to exist in the list.
Typedefs
typedef int(*)	ggzEntryCompare (const void *a, const void *b)
	A function type for doing data comparison on two items in a GGZList.
typedef void *(*)	ggzEntryCreate (void *data)
	A function type for creating a copy of a data item for insertion into a GGZList.
typedef void(*)	ggzEntryDestroy (void *data)
	A function type to destroy an entry in a GGZList.
typedef _GGZListEntry	GGZListEntry
	A single entry in a GGZList.
typedef _GGZList	GGZList
	Simple doubly-linked list.
Functions
GGZList *	ggz_list_create (ggzEntryCompare compare_func, ggzEntryCreate create_func, ggzEntryDestroy destroy_func, int options)
	Create a new GGZList.
int	ggz_list_insert (GGZList *list, void *data)
	Insert data into a list.
GGZListEntry *	ggz_list_head (GGZList *list)
	Get the first node of a list.
GGZListEntry *	ggz_list_tail (GGZList *list)
	Get the last node of a list.
GGZListEntry *	ggz_list_next (GGZListEntry *entry)
	Get the next node of a list.
GGZListEntry *	ggz_list_prev (GGZListEntry *entry)
	Get the previous node of a list.
void *	ggz_list_get_data (GGZListEntry *entry)
	Retrieve the data stored in a list entry.
GGZListEntry *	ggz_list_search (GGZList *list, void *data)
	Search for a specified data item in the list.
GGZListEntry *	ggz_list_search_alt (GGZList *list, void *data, ggzEntryCompare compare_func)
	Search for a specified data item in the list using a provided comparison function.
void	ggz_list_delete_entry (GGZList *list, GGZListEntry *entry)
	Removes an entry from a list, calling a destructor if registered.
void	ggz_list_free (GGZList *list)
	Free all resources associated with a list.
int	ggz_list_count (GGZList *list)
	Get the length of the list.
int	ggz_list_compare_str (void *a, void *b)
	Compare two character strings.
void *	ggz_list_create_str (void *data)
	Copy a character string.
void	ggz_list_destroy_str (void *data)
	Free a character string.

---

Detailed Description

Data Structures and functions for manipulating linked-lists.

---

Typedef Documentation

typedef int(*) ggzEntryCompare(const void *a, const void *b)

A function type for doing data comparison on two items in a GGZList.

Parameters:

	a	An arbitrary element in the GGZList.
	b	An arbitrary element in the GGZList.

Returns:

Negative if a < b; 0 if a == b; positive if a > b.

typedef void*(*) ggzEntryCreate(void *data)

A function type for creating a copy of a data item for insertion into a GGZList.

A function of this type may be called on an element when it is first inserted into a GGZList.

Parameters:

data

A pointer to the data given to the list for insertion

Returns:

A new copy of the data, safe for list insertion

typedef void(*) ggzEntryDestroy(void *data)

A function type to destroy an entry in a GGZList.

A function of this type may be called on an element when it is removed from a GGZList.

Parameters:

data

The entry being removed

typedef struct _GGZListEntry GGZListEntry

A single entry in a GGZList.

Do not access these members directly, but use the ggz_list_get_data(), ggz_list_next() and ggz_list_prev() accessor functions instead.

typedef struct _GGZList GGZList

Simple doubly-linked list.

Do not access these members directly. Instead use accessor functions.

---

Function Documentation

GGZList* ggz_list_create	(	ggzEntryCompare	compare_func,
		ggzEntryCreate	create_func,
		ggzEntryDestroy	destroy_func,
		int	options
	)

Create a new GGZList.

When creating a a new list, you have some control over its behavior. The first parameter, compare_func allows you to specify a comparison for sorting the list elements. If you specify NULL for compare_func, the list will be unordered. The second parameter, create_func allows you to specify how new copies of data will be created during insertion. GGZList objects stores pointers to your data in GGZListEntry nodes. If you specify NULL for create_func, the list will store the actual pointer to your data when you call ggz_list_insert(). If you specify a create_func, it will be called to create a new copy of the object for storage in the list. You are then safely deallocate the original copy of the data. The third parameter, destroy_func allows you to specify a deallocation function for data entries when they are removed from the list.

Note:

The functions ggz_list_compare_str(), ggz_list_create_str(), ggz_list_destroy_str() are provided for use with character string data.

The last argument must be one of GGZ_LIST_REPLACE_DUPS or GGZ_LIST_ALLOW_DUPS, to specify how the list will behave with respect to duplicate data entries. If GGZ_LIST_REPLACE_DUPS is passed, duplicate entries (as determined by compare_func) will be replaced upon ggz_list_insert(). If GGZ_LIST_ALLOW_DUPS is specified, duplicate data entries will be allowed to exist in the list.

Note:

If compare_func is NULL, GGZ_LIST_REPLACE_DUPS has no meaning.

Parameters:

	compare_func	Function to use for comparing data items
	create_func	Function to use for allocating and copying data items
	destroy_func	Function to use for dellocating data items
	options	One of GGZ_LIST_REPLACE_DUPS or GGZ_LIST_ALLOW_DUPS specifying how the list should handle duplicate data entries

Returns:

A pointer to a newly allocated GGZList

int ggz_list_insert	(	GGZList *	list,
		void *	data
	)

Insert data into a list.

Parameters:

	list	Pointer to a GGZList
	data	Pointer to data to be inserted

Returns:

-1 on failure, 0 is the item was inserted, and 1 if the item replaced an existing list item

Note:

Replacement of duplicate items only occurs if GGZ_LIST_REPLACE_DUPS was passed to ggz_list_create().

GGZListEntry* ggz_list_head

(

GGZList *

list

)

Get the first node of a list.

Parameters:

list

Pointer to a GGZList

Returns:

The GGZListEntry that is first in the list

GGZListEntry* ggz_list_tail

(

GGZList *

list

)

Get the last node of a list.

Parameters:

list

Pointer to a GGZList

Returns:

The GGZListEntry that is last in the list

GGZListEntry* ggz_list_next

(

GGZListEntry *

entry

)

Get the next node of a list.

Parameters:

entry

Pointer to a GGZListEntry in a GGZList

Returns:

The next GGZListEntry in the list

GGZListEntry* ggz_list_prev

(

GGZListEntry *

entry

)

Get the previous node of a list.

Parameters:

entry

Pointer to a GGZListEntry in a GGZList

Returns:

The previous GGZListEntry in the list

void* ggz_list_get_data

(

GGZListEntry *

entry

)

Retrieve the data stored in a list entry.

Parameters:

entry

Pointer to a GGZListEntry

Returns:

Pointer to the data stored in the specifed node (GGZListEntry)

GGZListEntry* ggz_list_search	(	GGZList *	list,
		void *	data
	)

Search for a specified data item in the list.

ggz_list_search() searches a list for a particular data item using the ggzEntryCompare function provided as compare_func to ggz_list_create(). If you wish to search using an alternative comparison function, see ggz_list_search_alt().

Parameters:

	list	Pointer to a GGZList
	data	Pointer to data to search for

Returns:

Pointer to the GGZListEntry containing the specifed node (NULL if the data could not be found or if no compare_func was specified at list-creation time)

GGZListEntry* ggz_list_search_alt	(	GGZList *	list,
		void *	data,
		ggzEntryCompare	compare_func
	)

Search for a specified data item in the list using a provided comparison function.

ggz_list_search_alt() searches a list for a particular data item using the passed ggzEntryCompare function.

Parameters:

	list	Pointer to a GGZList
	data	Pointer to data to search for
	compare_func	Comparison function

Returns:

Pointer to the GGZListEntry containing the specified node (NULL if the data could not be found or if no compare_func was specified)

void ggz_list_delete_entry	(	GGZList *	list,
		GGZListEntry *	entry
	)

Removes an entry from a list, calling a destructor if registered.

ggz_list_delete_entry() removes the specifed entry from the list. If a ggzEntryDestroy function was passed as destroy_func to ggz_list_create(), it will be called on the data item after it has been removed.

Parameters:

	list	Pointer to a GGZList
	entry	Pointer to the GGZListEntry to remove

void ggz_list_free

(

GGZList *

list

)

Free all resources associated with a list.

ggz_list_free() will free all resources allocated by the list. If a ggzEntryDestroy function was passed as destroy_func to ggz_list_create(), it will be called on all data items in the list as well.

Parameters:

list

Pointer to a GGZList

int ggz_list_count

(

GGZList *

list

)

Get the length of the list.

Parameters:

list

Pointer to a GGZList

Returns:

The number of entries in the list

int ggz_list_compare_str	(	void *	a,
		void *	b
	)

Compare two character strings.

This function is intended to be passed as the compare_func of ggz_list_create() when creating a list that stores character strings.

Parameters:

	a	A string to compare
	b	A second string to compare

Returns:

The result of strcmp() on a and b, or 1 if either is NULL

void* ggz_list_create_str

(

void *

data

)

Copy a character string.

This function is intended to be passed as the create_func of ggz_list_create() when creating a list that stores character strings.

Parameters:

data

A string to copy

Returns:

A newly allocated copy of the string

void ggz_list_destroy_str

(

void *

data

)

Free a character string.

This function is intended to be passed as the destroy_func of ggz_list_create() when creating a list that stores character strings.

Parameters:

data

The string to deallocate

---