c_list.h File Reference

Detailed Description

c_list -- a doubly-linked list.

The c_list_t structure and its associated functions provide a standard doubly-linked list data structure. Each node has two links: one points to the previous node, or points to a null value or empty list if it is the first node; and one points to the next, or points to a null value or empty list if it is the final node.

The data contained in each element can be simply pointers to any type of data. You are the owner of the data, this means you have to free the memory you have allocated for the data.

Definition in file c_list.h.

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

Typedef Documentation

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

Specifies the type of a comparison function used to compare two values.

The value which should be returned depends on the context in which the c_list_compare_fn is used.

Parameters:

	a	First parameter to compare with.
	b	Second parameter to compare with.

Returns:: The function should return a number > 0 if the first parameter comes after the second parameter in the sort order.

Definition at line 83 of file c_list.h.

c_list_t

Creates a type name for c_list_s.

Definition at line 50 of file c_list.h.

Function Documentation

c_list_t* c_list_alloc ( void )

Allocates space for one c_list_t element.

Returns:: A pointer to the newly-allocated element.

c_list_t* c_list_append	(	c_list_t *	list,
		void *	data
	)

Adds a new element on to the end of the list.

Parameters:

	list	A pointer to c_list.
	data	The data for the new element.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

c_list_t* c_list_find	(	c_list_t *	list,
		void *	data
	)

Finds the element in a c_list_t which contains the given data.

Parameters:

	list	A pointer to c_list.
	data	The data of the element to remove.

Returns:: The found element or NULL if it is not found.

c_list_t* c_list_find_custom	(	c_list_t *	list,
		void *	data,
		c_list_compare_fn	func
	)

Finds an element, using a supplied function to find the desired element.

Parameters:

	list	A pointer to c_list.
	data	The data of the element to remove.
	func	The function to call for each element. It should return 0 when the desired element is found.

Returns:: The found element or NULL if it is not found.

c_list_t* c_list_first ( c_list_t * list )

Gets the first element in a c_list.

Parameters:

list

A pointer to c_list.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

void c_list_free ( c_list_t * list )

Frees all elements from a c_list.

Parameters:

list

A pointer to c_list.

c_list_t* c_list_insert	(	c_list_t *	list,
		void *	data,
		long	position
	)

Inserts a new element into the list at the given position.

If the position is lesser than 0, the new element gets appended to the list, if the position is 0, we prepend the element and if the given position is greater than the length of the list, the element gets appended too.

Parameters:

	list	A pointer to c_list.
	data	The data for the new element.
	position	The position to insert the element.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

c_list_t* c_list_insert_sorted	(	c_list_t *	list,
		void *	data,
		c_list_compare_fn	func
	)

Inserts a new element into the list, using the given comparison function to determine its position.

Parameters:

	list	A pointer to c_list.
	data	The data for the new element.
	func	The function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

c_list_t* c_list_last ( c_list_t * list )

Gets the last element in a c_list.

Parameters:

list

A pointer to c_list.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

unsigned long c_list_length ( c_list_t * list )

Gets the number of elements in a c_list.

Parameters:

list

A pointer to c_list.

Returns:: The number of elements

c_list_t* c_list_next ( c_list_t * list )

Gets the next element in a c_list.

Parameters:

An

element in a c_list.

Returns:: The next element, or NULL if there are no more elements.

c_list_t* c_list_position	(	c_list_t *	list,
		long	position
	)

Gets the element at the given positon in a c_list.

Parameters:

	list	A pointer to c_list.
	position	The position of the element, counting from 0.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

c_list_t* c_list_prepend	(	c_list_t *	list,
		void *	data
	)

Adds a new element on at the beginning of the list.

Parameters:

	list	A pointer to c_list.
	data	The data for the new element.

Returns:: New start of the list, which may have changed, so make sure you store the new value.

c_list_t* c_list_prev ( c_list_t * list )

Gets the previous element in a c_list.

Parameters:

An

element in a c_list.

Returns:: The previous element, or NULL if there are no more elements.

c_list_t* c_list_remove	(	c_list_t *	list,
		void *	data
	)

Removes an element from a c_list.

If two elements contain the same data, only the first is removed.

Parameters:

	list	A pointer to c_list.
	data	The data of the element to remove.

c_list_t* c_list_sort	(	c_list_t *	list,
		c_list_compare_fn	func
	)

Sorts the elements of a c_list.

The algorithm used is Mergesort, because that works really well on linked lists, without requiring the O(N) extra space it needs when you do it on arrays.

Parameters:

	list	A pointer to c_list.
	func	The comparison function used to sort the c_list. This function is passed 2 elements of the GList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second.

Returns:: New start of the list, which may have changed, so make sure you store the new value.


Data Structures
struct	c_list_s
	Used for each element in a doubly-linked list. More...
Typedefs
typedef int(*	c_list_compare_fn )(const void a, const void b)
typedef struct c_list_s	c_list_t
Functions
c_list_t *	c_list_alloc (void)
c_list_t *	c_list_append (c_list_t list, void data)
c_list_t *	c_list_find (c_list_t list, void data)
c_list_t *	c_list_find_custom (c_list_t list, void data, c_list_compare_fn func)
c_list_t *	c_list_first (c_list_t *list)
void	c_list_free (c_list_t *list)
c_list_t *	c_list_insert (c_list_t list, void data, long position)
c_list_t *	c_list_insert_sorted (c_list_t list, void data, c_list_compare_fn func)
c_list_t *	c_list_last (c_list_t *list)
unsigned long	c_list_length (c_list_t *list)
c_list_t *	c_list_next (c_list_t *list)
c_list_t *	c_list_position (c_list_t *list, long position)
c_list_t *	c_list_prepend (c_list_t list, void data)
c_list_t *	c_list_prev (c_list_t *list)
c_list_t *	c_list_remove (c_list_t list, void data)
c_list_t *	c_list_sort (c_list_t *list, c_list_compare_fn func)

c_list.h File Reference

Detailed Description

Data Structures

Typedefs

Functions

Typedef Documentation

Function Documentation