doc
Data Structures | Typedefs | Functions
c_list.h File Reference

Go to the source code of this file.

Data Structures

struct  c_list_s
 

Typedefs

typedef int(* c_list_compare_fn) (const void *a, const void *b)
 
typedef struct c_list_s c_list_t
 

Functions

c_list_tc_list_alloc (void)
 
c_list_tc_list_append (c_list_t *list, void *data)
 
c_list_tc_list_find (c_list_t *list, const void *data)
 
c_list_tc_list_find_custom (c_list_t *list, const void *data, c_list_compare_fn fn)
 
c_list_tc_list_first (c_list_t *list)
 
void c_list_free (c_list_t *list)
 
c_list_tc_list_insert (c_list_t *list, void *data, long position)
 
c_list_tc_list_insert_sorted (c_list_t *list, void *data, c_list_compare_fn fn)
 
c_list_tc_list_last (c_list_t *list)
 
unsigned long c_list_length (c_list_t *list)
 
c_list_tc_list_next (c_list_t *list)
 
c_list_tc_list_position (c_list_t *list, long position)
 
c_list_tc_list_prepend (c_list_t *list, void *data)
 
c_list_tc_list_prev (c_list_t *list)
 
c_list_tc_list_remove (c_list_t *list, void *data)
 
c_list_tc_list_sort (c_list_t *list, c_list_compare_fn func)
 

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.

Typedef Documentation

◆ c_list_compare_fn

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
aFirst parameter to compare with.
bSecond 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 80 of file c_list.h.

◆ c_list_t

Creates a type name for c_list_s.

Definition at line 47 of file c_list.h.

Function Documentation

◆ c_list_alloc()

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_append()

c_list_t* c_list_append ( c_list_t list,
void *  data 
)

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

Parameters
listA pointer to c_list.
dataThe 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_find()

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

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

Parameters
listA pointer to c_list.
dataThe data of the element to remove.
Returns
The found element or NULL if it is not found.

◆ c_list_find_custom()

c_list_t* c_list_find_custom ( c_list_t list,
const void *  data,
c_list_compare_fn  fn 
)

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

Parameters
listA pointer to c_list.
dataThe data of the element to remove.
funcThe 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_first()

c_list_t* c_list_first ( c_list_t list)

Gets the first element in a c_list.

Parameters
listA pointer to c_list.
Returns
New start of the list, which may have changed, so make sure you store the new value.

◆ c_list_free()

void c_list_free ( c_list_t list)

Frees all elements from a c_list.

Parameters
listA pointer to c_list.

◆ c_list_insert()

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
listA pointer to c_list.
dataThe data for the new element.
positionThe 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_insert_sorted()

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

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

Parameters
listA pointer to c_list.
dataThe data for the new element.
fnThe 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_last()

c_list_t* c_list_last ( c_list_t list)

Gets the last element in a c_list.

Parameters
listA pointer to c_list.
Returns
New start of the list, which may have changed, so make sure you store the new value.

◆ c_list_length()

unsigned long c_list_length ( c_list_t list)

Gets the number of elements in a c_list.

Parameters
listA pointer to c_list.
Returns
The number of elements

◆ c_list_next()

c_list_t* c_list_next ( c_list_t list)

Gets the next element in a c_list.

Parameters
Anelement in a c_list.
Returns
The next element, or NULL if there are no more elements.

◆ c_list_position()

c_list_t* c_list_position ( c_list_t list,
long  position 
)

Gets the element at the given positon in a c_list.

Parameters
listA pointer to c_list.
positionThe 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_prepend()

c_list_t* c_list_prepend ( c_list_t list,
void *  data 
)

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

Parameters
listA pointer to c_list.
dataThe 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_prev()

c_list_t* c_list_prev ( c_list_t list)

Gets the previous element in a c_list.

Parameters
Anelement in a c_list.
Returns
The previous element, or NULL if there are no more elements.

◆ c_list_remove()

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
listA pointer to c_list.
dataThe data of the element to remove.
Returns
The first element of the list, NULL on error.

◆ c_list_sort()

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
listA pointer to c_list.
funcThe 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.