c_list.c File Reference

#include "c_list.h"
#include <stdlib.h>
#include <string.h>

Include dependency graph for c_list.c:

Data Structures
struct	c_data_node
struct	c_list_type

Typedefs
typedef struct c_data_node	c_data_node_type

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

Typedef Documentation

typedef struct c_data_node c_data_node_type

Data for each linked list node

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	p,
		const void *	elm_ptr
	)

uint32_t c_list_node_count

(

const c_list_ptr

list

)

Returns

the number of items in the list.