Lists

Overview

The Lists module implements a linked list. Elements - actually element pointers - can be appended at the end of an u_list_t object (via u_list_add), or inserted at a given position (via u_list_insert). Element can be retrieved and deleted by index (u_list_get_n, u_list_del_n), and also evicted by direct reference (u_list_del). The u_list_foreach iterator is provided for safe, easy and efficient (forward) traversal of list objects.

Note:: Element pointers are never owned by the u_list_t object to which they are linked. The disposal of the resources (possibly) allocated on the element is up to the user, e.g. when calling u_list_del_n, use the result-argument *pptr to pass the "real" object to its dtor.

Defines
#define	u_list_foreach(list, n, it) for(n = u_list_first(list, &it); n; n = u_list_next(list, &it))
	List iterator.
#define	u_list_iforeach(list, n, it, i) for(i = 0, n = u_list_first(list, &it); n; n = u_list_next(list, &it), ++i)
	List iterator with iteration counter.
Typedefs
typedef struct u_list_s	u_list_t
	Basic list object type.
Functions
int	u_list_create (u_list_t **plist)
	Create a new list object.
void	u_list_free (u_list_t *list)
	Free a list object.
int	u_list_clear (u_list_t *list)
	Remove all elements from the list.
int	u_list_add (u_list_t list, void ptr)
	Push an element to the list.
int	u_list_insert (u_list_t list, void ptr, size_t n)
	Insert an element at the given position.
int	u_list_del (u_list_t list, void ptr)
	Pop an element from the list.
int	u_list_del_n (u_list_t list, size_t n, void *pptr)
	Delete an element given its position in the list.
void *	u_list_get_n (u_list_t *list, size_t n)
	Get the n-th element in list.
size_t	u_list_count (u_list_t *list)
	Count elements in list.
void *	u_list_first (u_list_t list, void *it)
	Return the first item of the list and initialize the iterator.
void *	u_list_next (u_list_t list, void *it)
	Return the next element while iterating over a list.

Define Documentation

#define u_list_foreach	(	list,
		n,
		it	)	for(n = u_list_first(list, &it); n; n = u_list_next(list, &it))

Parameters:

	list	an u_list_t object
	n	a variable that will get the current value from `list`
	it	an opaque iterator with type `void**`

Definition at line 31 of file list.h.

#define u_list_iforeach	(	list,
		n,
		it,
		i	)	for(i = 0, n = u_list_first(list, &it); n; n = u_list_next(list, &it), ++i)

Parameters:

	list	an u_list_t object
	n	a variable that will get the current value from `list`
	it	an opaque iterator with type `void**`
	i	variable of type `integer` that will be get the iteration counter (0..i)

Definition at line 42 of file list.h.

Function Documentation

int u_list_add	(	u_list_t *	list,
		void *	ptr
	)

Push the supplied pointer ptr to the u_list_t object list

Parameters:

	list	the parent u_list_t object (created via u_list_create)
	ptr	the the reference to the element that has to be push'd

Return values:

	0	on success
	~0	on failure

Definition at line 97 of file srcs/toolbox/list.c.

References u_list_insert().

int u_list_clear ( u_list_t * list )

Remove all elements from the supplied u_list_t object list. Beware that the referenced objects - if any - won't be available anymore and could be lost (usually causing memory leaking).

Parameters:

list

the u_list_t object that must be reset

Return values:

	0	on success
	~0	on failure

Definition at line 353 of file srcs/toolbox/list.c.

References u_free().

Referenced by u_list_free().

size_t u_list_count ( u_list_t * list )

Count the number of elements actually present in the supplied u_list_t object list

Parameters:

list

the u_list_t object that has to be queried

Returns:: the number of elements in list

Definition at line 141 of file srcs/toolbox/list.c.

int u_list_create ( u_list_t ** plist )

Parameters:

plist

the newly created u_list_t object as a result argument

Return values:

	0	on success
	~0	on failure

Definition at line 47 of file srcs/toolbox/list.c.

References u_free(), and u_zalloc().

int u_list_del	(	u_list_t *	list,
		void *	ptr
	)

Evict the element referenced by ptr from the u_list_t object list

Parameters:

	list	the parent u_list_t object (created via u_list_create)
	ptr	reference to the element that has to be evicted

Return values:

	0	if `ptr` has been successfully removed
	~0	if `ptr` was not found

Definition at line 113 of file srcs/toolbox/list.c.

References u_free().

int u_list_del_n	(	u_list_t *	list,
		size_t	n,
		void **	pptr
	)

Delete the element at index n from the supplied u_list_t object list and give back the reference to the stored object via the result argument pptr. At a later stage *pptr can be appropriately destroyed.

Parameters:

	list	the parent u_list_t object (created via u_list_create)
	n	element position in the list
	pptr	element reference

Return values:

	0	if `ptr` has been removed
	~0	if `ptr` was not found

Definition at line 316 of file srcs/toolbox/list.c.

References u_free().

void * u_list_first	(	u_list_t *	list,
		void **	it
	)

Return the first item of the supplied u_list_t object and initialize the opaque iterator it

Parameters:

	list	the u_list_t object (created via u_list_create)
	it	opaque iterator object of type `void**`

Returns:: the first item or NULL if the list is empty

Definition at line 236 of file srcs/toolbox/list.c.

void u_list_free ( u_list_t * list )

Free the supplied u_list_t object list. Note the list doesn't own the pointers in it: the client must free them

Parameters:

list

the u_list_t object that has to be disposed

Returns:: nothing

Definition at line 75 of file srcs/toolbox/list.c.

References u_free(), and u_list_clear().

void * u_list_get_n	(	u_list_t *	list,
		size_t	n
	)

Get the element at index position n from the u_list_t object list

Parameters:

	list	an u_list_t object
	n	the index of the element that we are supposed to retrieve

Returns:: the pointer to the n-th element or NULL if no element was found at index n

Definition at line 159 of file srcs/toolbox/list.c.

int u_list_insert	(	u_list_t *	list,
		void *	ptr,
		size_t	n
	)

Insert the supplied element ptr into the u_list_t object list at index n

Parameters:

	list	the parent u_list_t object (created via u_list_create)
	ptr	the element that has to be push'd
	n	the position in the list (from zero to u_list_count)

Return values:

	0	on success
	~0	on failure

Definition at line 188 of file srcs/toolbox/list.c.

References u_free(), and u_zalloc().

Referenced by u_list_add().

void * u_list_next	(	u_list_t *	list,
		void **	it
	)

Return the next element while iterating over the supplied u_list_t object list. The it iterator must have been already initialized via a previous call to u_list_first

Parameters:

	list	an u_list_t object created via u_list_create
	it	opaque iterator already initialized with u_list_first

List iteration example:

    void *it;
    my_t *my;

    // indifferently one could have used: u_list_foreach (list, my, it) { ... }
    for (my = u_list_first(list, &it); my; my = u_list_next(list, &it))
        do_something_with(my);
    ...

Returns:: the requested item or NULL if the last item in list was reached

See also:: u_list_foreach; u_list_iforeach

Definition at line 281 of file srcs/toolbox/list.c.

Lists

Overview

Defines

Typedefs

Functions

Define Documentation

Function Documentation