list.h File Reference

Double-linked non-intrusive list. More...

Go to the source code of this file.

Data Structures
struct	list_node
struct	list
Functions
struct list *	list_create ()
	Create a new linked list.
struct list *	list_duplicate (struct list *list)
	Duplicate a linked list Returns a copy of the linked list.
void	list_delete (struct list *list)
	Delete a linked list.
void	list_free (struct list *list)
	Free every item referred to by the list.
struct list *	list_splice (struct list *top, struct list *bottom)
	Splice two lists together.
struct list *	list_split (struct list *src, list_op_t cmp, const void *arg)
	Split a list into two at the given item If arg is NULL or not found, list_split returns NULL and the list is unaffected.
int	list_size (struct list *list)
	Count the elements in a list.
int	list_push_priority (struct list *list, void *item, int prio)
	Push an item in priority order.
int	list_push_head (struct list *list, void *item)
	Push an item onto the list head.
void *	list_pop_head (struct list *list)
	Pop an item off of the list head.
void *	list_peek_head (struct list *list)
	Peek at the list head.
int	list_push_tail (struct list *list, void *item)
	Push an item onto the list tail.
void *	list_pop_tail (struct list *list)
	Pop an item off of the list tail.
void *	list_peek_tail (struct list *list)
	Peek at the list tail.
void *	list_find (struct list *list, list_op_t cmp, const void *arg)
	Find an element within a list This function searches the list, comparing each element in the list to arg, and returns a pointer to the first matching element.
void *	list_remove (struct list *list, const void *value)
	Remove an item from the list This function searches the list for the item pointed to by value and removes it.
void	list_first_item (struct list *list)
	Begin traversing a list.
void *	list_next_item (struct list *list)
	Continue traversing a list.
int	list_iterate (struct list *list, list_op_t op, const void *arg)
	Apply a function to a list.
int	list_iterate_reverse (struct list *list, list_op_t op, const void *arg)
	Apply a function to a list in reverse.
struct list *	list_sort (struct list *list, int(*comparator)(const void *, const void *))
	Sort a list using a comparator function.

---

Detailed Description

Double-linked non-intrusive list.

---

Function Documentation

struct list* list_create

(

)

[read]

Create a new linked list.

Returns:

A pointer to an empty linked list.

struct list* list_duplicate

(

struct list *

list

)

[read]

Duplicate a linked list Returns a copy of the linked list.

Note that the pointers in both lists point to the same places.

Parameters:

list

The list to be duplicated

Returns:

A pointer to the duplicate list

void list_delete

(

struct list *

list

)

Delete a linked list.

Note that this function only deletes the list itself, it does not delete the items referred to by the list.

Parameters:

list

The list to delete.

void list_free

(

struct list *

list

)

Free every item referred to by the list.

Note that this function does not delete the list itself.

Parameters:

list

The list to free.

struct list* list_splice	(	struct list *	top,
		struct list *	bottom
	)			[read]

Splice two lists together.

Parameters:

	top	A linked list that will be destroyed in the process.
	bottom	A linked list that will be destroyed in the process.

Returns:

A new linked list with elements from top at the head and bottom at the tail.

struct list* list_split	(	struct list *	src,
		list_op_t	cmp,
		const void *	arg
	)			[read]

Split a list into two at the given item If arg is NULL or not found, list_split returns NULL and the list is unaffected.

Otherwise src will contain all elements [src->head, arg) and a new list will be created with all elements [arg, src->tail].

Parameters:

	src	The linked list to be split
	cmp	The comparison function. Should return non-zero on a match.
	arg	The data element to split on.

Returns:

A new linked list with arg as the head and all elements after arg as elements of the new list.

int list_size

(

struct list *

list

)

Count the elements in a list.

Parameters:

list

The list to count.

Returns:

The number of items stored in the list.

int list_push_priority	(	struct list *	list,
		void *	item,
		int	prio
	)

Push an item in priority order.

Parameters:

	list	The list to push onto.
	item	The item to push onto the list.
	prio	The integer priority of the item.

Returns:

True on success, false on failure (due to out of memory.)

int list_push_head	(	struct list *	list,
		void *	item
	)

Push an item onto the list head.

Parameters:

	list	The list to push onto.
	item	The item to push onto the list.

Returns:

True on success, false on failure (due to out of memory.)

void* list_pop_head

(

struct list *

list

)

Pop an item off of the list head.

Parameters:

list

The list to pop.

Returns:

The item popped, or null if list is empty.

void* list_peek_head

(

struct list *

list

)

Peek at the list head.

Parameters:

list

The list to peek.

Returns:

The item at the list head, or null if list is empty.

int list_push_tail	(	struct list *	list,
		void *	item
	)

Push an item onto the list tail.

Parameters:

	list	The list to push onto.
	item	The item to push onto the list.

Returns:

True on success, false on failure (due to out of memory.)

void* list_pop_tail

(

struct list *

list

)

Pop an item off of the list tail.

Parameters:

list

The list to pop.

Returns:

The item popped, or null if list is empty.

void* list_peek_tail

(

struct list *

list

)

Peek at the list tail.

Parameters:

list

The list to peek.

Returns:

The item at the list tail, or null if list is empty.

void* list_find	(	struct list *	list,
		list_op_t	cmp,
		const void *	arg
	)

Find an element within a list This function searches the list, comparing each element in the list to arg, and returns a pointer to the first matching element.

Parameters:

	list	The list to search
	cmp	The comparison function. Should return non-zero on a match.
	arg	The element to compare against

Returns:

A pointer to the first matched element, or NULL if no elements match.

void* list_remove	(	struct list *	list,
		const void *	value
	)

Remove an item from the list This function searches the list for the item pointed to by value and removes it.

Parameters:

	list	The list to search
	value	The item to remove

Returns:

The removed item.

void list_first_item

(

struct list *

list

)

Begin traversing a list.

This function sets the internal list iterator to the first item. Call list_next_item to begin returning the items.

Parameters:

list

The list to traverse.

void* list_next_item

(

struct list *

list

)

Continue traversing a list.

This function returns the current list item, and advances the internal iterator to the next item.

Parameters:

list

The list to traverse.

Returns:

The current item in the list.

int list_iterate	(	struct list *	list,
		list_op_t	op,
		const void *	arg
	)

Apply a function to a list.

Invokes op on every member of the list.

Parameters:

	list	The list to operate on.
	op	The operator to apply.
	arg	An optional parameter to send to op.

int list_iterate_reverse	(	struct list *	list,
		list_op_t	op,
		const void *	arg
	)

Apply a function to a list in reverse.

Invokes op on every member of the list in reverse.

Parameters:

	list	The list to operate on.
	op	The operator to apply.
	arg	An optional parameter to send to op.

struct list* list_sort	(	struct list *	list,
		int(*)(const void *, const void *)	comparator
	)			[read]

Sort a list using a comparator function.

Parameters:

	list	The list to sort.
	comparator	The comparison function used in the sort. The function should take in pointers to two objects casted as void* and return an integer indicating whether the first is less than (negative), equal to (0), or greater than (positive) the second.

Returns:

A pointer to the list passed in. Identical to the list parameter.