c_list.h File Reference

#include <stdint.h>
#include <stdbool.h>

Include dependency graph for c_list.h:

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

Go to the source code of this file.

Typedefs
typedef bool(*	c_list_callback_t) (void *elm_ptr, void *arg1, void *arg2, void *arg3)
typedef void *	c_list_ptr

Functions
c_list_ptr	c_list_create (void)
bool	c_list_delete (c_list_ptr list, c_list_callback_t delete_callback)
uint32_t	c_list_node_count (const c_list_ptr list)
void *	c_list_get_elm_at (c_list_ptr list, uint32_t index, void **hint)
void *	c_list_find_elm (c_list_ptr list, c_list_callback_t callback, void *arg1, void *arg2, void *arg3)
bool	c_list_delete_elm (c_list_ptr list, const void *elm_ptr)
bool	c_list_for_each_elm (const c_list_ptr list, c_list_callback_t func, void *arg1, void *arg2, void *arg3)
bool	c_list_insert_elm_beg (c_list_ptr list, const void *elm_ptr)
bool	c_list_insert_elm_end (c_list_ptr list, const void *elm_ptr)

Detailed Description

Linked list implementation in C. This is a SINGLY linked list with the head and the tail pointers, therefore insertion at either at the head or the tail will be quick.

Note

This linked list doesn't copy data internally; it only keeps the link aka pointer to your data that you need to maintain yourself. In other words: Make sure the linked data doesn't go out of scope otherwise the list will basically contain 'dangling' pointer(s).

Example code of list of integer pointers :

bool print_callback(void *elm_ptr, void *arg1, void *arg2, void *arg3)
{
    printf("Value = %i\n", *(int*)elm_ptr);
    return true;
}
bool delete_callback(void *elm_ptr, void *arg1, void *arg2, void *arg3)
{
    free(elm_ptr);
    return true;
}

c_list_ptr list = c_list_create();
int *a = malloc(sizeof(int));
int *b = malloc(sizeof(int));
*a = 1;
*b = 2;
c_list_insert_elm_beg(list, a);
c_list_insert_elm_end(list, b);

// This will print 1 and 2 by our print_callback()
c_list_for_each_elm(list, print_callback, NULL, NULL, NULL);

// Delete our list and free up "a" and "b"
c_list_delete(list, delete_callback);

Typedef Documentation

typedef bool(* c_list_callback_t) (void *elm_ptr, void *arg1, void *arg2, void *arg3)

INCLUDES COMMON

typedef void* c_list_ptr

Typedef of the c-list pointer type. User shouldn't need to know about the internal structure of the list.

Function Documentation

c_list_ptr c_list_create

(

void

)

Creates a linked list structure

Returns

Heap allocated list pointer.

bool c_list_delete	(	c_list_ptr	list,
		c_list_callback_t	delete_callback
	)

Deletes the linked list and calls your del() function for each element.

Parameters

list	The linked list pointer.
delete_callback	This can be NULL if you just want to free up the list and its nodes and you don't want to use the delete callback. If you provide this callback, then you will receive a callback with the elm_ptr and you decide what to do with the pointers you added to the list.

bool c_list_delete_elm	(	c_list_ptr	list,
		const void *	elm_ptr
	)

Deletes an element by the pointer

Parameters

list	The list to delete the node from
elm_ptr	Pointer to the element that should be deleted. Note that this will delete the first element it finds and will not remove all instances if duplicate elements were added.

Returns

true if element was found and was deleted.

void* c_list_find_elm	(	c_list_ptr	list,
		c_list_callback_t	callback,
		void *	arg1,
		void *	arg2,
		void *	arg3
	)

Finds an element in the list. When your callback returns false, this function will return that element back. If your callback returns true and list iteration finishes, NULL pointer is returned.

Parameters

list	The list to iterate
callback	The callback function.
arg1	arg2 arg3 The arguments to pass to your call-back function.

bool c_list_for_each_elm	(	const c_list_ptr	list,
		c_list_callback_t	func,
		void *	arg1,
		void *	arg2,
		void *	arg3
	)

Iterates your list's element(s)

Parameters

list	The list to iterate
func	The callback function. The list will iterate as long as this callback function returns true. When the callback function returns false, the iteration stops and immediately returns false. If iteration finished and your callback always returned true, then this function will also return true.
arg1	arg2 arg3 The arguments to pass to your call-back function.

Returns

true if entire list was iterate without your callback returning false

If your list contains integers, you can use the following to check for duplicates :

static bool check_dup(void *elm, void *new_int, void *arg2_unused, void *arg3_unused)
{
    // Return true when we want c_list_for_each_elm() to continue
    return( *(int*)elm != *(int*)new_int);
}

if (!c_list_for_each_elm(list, check_dup, (void*)new_var_ptr, NULL, NULL))
{
    // Duplicate insertion when c_list_for_each_elm() returns false
}

void* c_list_get_elm_at	(	c_list_ptr	list,
		uint32_t	index,
		void **	hint
	)

Gets the linked list element at the given index.

Parameters

list	The list pointer
index	The index location with bounds of 0 to c_list_node_count()
hint	Can be NULL if you don't want to use it. You can use the hint to iterate through the elements faster if you are using a for loop. See example below : void *hint = 0; for(int i=0; i < c_list_node_count(my_list); i++) { void *my_elm = c_list_get_elm_at(my_list, i, &hint); }

Returns

The element pointer or NULL if out of bound element is accessed

bool c_list_insert_elm_beg	(	c_list_ptr	list,
		const void *	elm_ptr
	)

List insertion functions Inserts your data pointer to the list

Parameters

list	The list to insert a new node
elm_ptr	Pointer to your data.

Note

The data at elm is not copied internally, only the pointer is copied. This pointer thus, should not go out of scope after you add to the list.

bool c_list_insert_elm_end	(	c_list_ptr	list,
		const void *	elm_ptr
	)

uint32_t c_list_node_count

(

const c_list_ptr

list

)

Returns

the number of items in the list.