Data Structures
struct	tou_llist_t
	Linked list struct definition, typedef'd. More...

Macros
#define	tou_llist_new(...) ((TOU_DBG ? fprintf(stdout,TOU_DEBUG_PREFIX"Creating new llist :: NULL\n") : (void)0) , NULL)
	Creates/initializes new llist.

#define	tou_llist_gather tou_llist_gather_dat1
	Convenience alias for gathering first element.

#define	tou_llist_print(llist, dat1_spec, dat2_spec, ...)
	Macro that goes through the elements from head to tail and prints their `.dat1` and `.dat2` fields using given format specifiers.

#define	tou_llist_print_tail(llist, dat1_spec, dat2_spec, ...)
	Macro that goes through the elements from tail to head and prints their `.dat1` and `.dat2` fields using given format specifiers.

Functions
tou_llist_t *	tou_llist_append (tou_llist_t *elem, void dat1, void *dat2, char dat1_is_dynalloc, char dat2_is_dynalloc)
	Appends a brand new element to the list/given element and updates it in place.

tou_llist_t *	tou_llist_appendone (tou_llist_t *elem, void dat1, char dat1_is_dynalloc)
	Appends a brand new element to the list/given element which contains only `dat1` and if the pointer was the head, updates it in place.

tou_llist_t *	tou_llist_prepend (tou_llist_t *elem, void dat1, void *dat2, char dat1_is_dynalloc, char dat2_is_dynalloc)
	Prepends a brand new element to the list/given element.

tou_llist_t *	tou_llist_prependone (tou_llist_t *elem, void dat1, char dat1_is_dynalloc)
	Prepends a brand new element to the list/given element which only contains `dat1`.

void	tou_llist_destroy (tou_llist_t *list)
	Traverses elements using .next or .prev and frees each one including copied category string.

tou_llist_t *	tou_llist_remove (tou_llist_t *elem)
	Removes an element from llist and deallocates it.

tou_llist_t *	tou_llist_pop (tou_llist_t *elem)
	Disconnects an element from llist but does not deallocate it.

void	tou_llist_free_element (tou_llist_t *elem)
	Frees an element and its contents.

tou_llist_t *	tou_llist_get_head (tou_llist_t *list)
	Traverses the whole list using `.next` and returns the last element that was added into list (where `.next` is NULL)

tou_llist_t *	tou_llist_get_tail (tou_llist_t *list)
	Traverses the whole list using `.prev` and returns the first element that was added to list (where `.prev` is NULL)

tou_llist_t *	tou_llist_get_newest (tou_llist_t *list)
	Returns the element that was added to the list last.

tou_llist_t *	tou_llist_get_oldest (tou_llist_t *list)
	Returns the element that was added to the list first.

tou_llist_t *	tou_llist_get_newer (tou_llist_t *elem)
	Returns the element added after `elem`.

tou_llist_t *	tou_llist_get_older (tou_llist_t *elem)
	Returns the element added before `elem`.

tou_llist_t *	tou_llist_next_newer (tou_llist_t **elem)
	Updates `elem` to point to the element added after itself.

tou_llist_t *	tou_llist_next_older (tou_llist_t **elem)
	Updates `elem` to point to the element added before itself.

char	tou_llist_is_head (tou_llist_t *elem)
	Checks if element is head of the list (`.next` should be NULL)

char	tou_llist_is_tail (tou_llist_t *elem)
	Checks if element is tail of the list (`.prev` should be NULL)

void	tou_llist_iter (tou_llist_t *list, tou_func cb)
	Iterate through and call the specified function for each element Automatically checks whether given element is head or tail and iterates accordingly.

tou_llist_t *	tou_llist_find_exact (tou_llist_t list, void dat1, void *dat2)
	Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison using both parameters at the same time.

tou_llist_t *	tou_llist_find_exactone (tou_llist_t list, void dat1)
	Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison of param.

tou_llist_t *	tou_llist_find_key (tou_llist_t list, void dat1)
	Traverses the list starting from the passed element and tries to find the first matching element on the basis: if dat1 is not null, tries to match it as a nul-terminated string.

tou_llist_t *	tou_llist_find_func (tou_llist_t list, tou_func2 cb, void userdata)
	Traverses the list starting from the passed element and tries to find the first matching element by checking the return value of the given callback comparison function.

size_t	tou_llist_len (tou_llist_t *list)
	Goes through the list and returns amount of elements.

void **	tou_llist_gather_dat1 (tou_llist_t list, size_t len)
	Constructs a dynamically allocated ARRAY containing only .dat1 properties (stored as void*).

void **	tou_llist_gather_dat2 (tou_llist_t list, size_t len)
	Constructs a dynamically allocated ARRAY containing only .dat2 properties (stored as void*).

Detailed Description

Macro Definition Documentation

◆ tou_llist_new

#define tou_llist_new ( ... ) ((TOU_DBG ? fprintf(stdout,TOU_DEBUG_PREFIX"Creating new llist :: NULL\n") : (void)0) , NULL)

Creates/initializes new llist.

Define creation of a new llist through #define so even though it currently doesn't require anything more than =NULL it will be easier to extend in the future if a need for such initializer arises.

◆ tou_llist_print

#define tou_llist_print	(	llist,
		dat1_spec,
		dat2_spec,
		... )

Value:

    {                                                                              \
        tou_llist_t* copy = tou_llist_get_newest(llist);                           \
        printf("List contents: (%d)\n", tou_llist_len(copy));                      \
        while (copy) {                                                             \
            printf("  |\n  "dat1_spec" :: "dat2_spec"\n", copy->dat1, copy->dat2); \
            copy = tou_llist_get_older(copy);                                      \
        }                                                                          \
    } (void)0

Macro that goes through the elements from head to tail and prints their .dat1 and .dat2 fields using given format specifiers.

If TOU_LLIST_SINGLE_ELEM is defined it will accept only dat1_spec and print only .dat1 (dat2_spec will be ignored if specified).

It is not enough if for example your wish is to print the value of int*, but if you just want that pointer, string or if you stored value itself into the field it will come in handy.

Parameters

[in]	llist	List to print
[in]	dat1_spec	Format specifier for `.dat1`
[in]	dat2_spec	Format specifier for `.dat2`

◆ tou_llist_print_tail

#define tou_llist_print_tail	(	llist,
		dat1_spec,
		dat2_spec,
		... )

Value:

    {                                                                              \
        tou_llist_t* copy = tou_llist_get_oldest(llist);                           \
        printf("List contents: (%d)\n", tou_llist_len(copy));                      \
        while (copy) {                                                             \
            printf("  |\n  "dat1_spec" :: "dat2_spec"\n", copy->dat1, copy->dat2); \
            copy = tou_llist_get_newer(copy);                                      \
        }                                                                          \
    } (void)0

Macro that goes through the elements from tail to head and prints their .dat1 and .dat2 fields using given format specifiers.

If TOU_LLIST_SINGLE_ELEM is defined it will accept only dat1_spec and print only .dat1 (dat2_spec will be ignored if specified).

It is not enough if for example your wish is to print the value of int*, but if you just want that pointer, string or if you stored value itself into the field it will come in handy.

Parameters

[in]	llist	List to print
[in]	dat1_spec	Format specifier for `.dat1`
[in]	dat2_spec	Format specifier for `.dat2`

Function Documentation

◆ tou_llist_append()

tou_llist_t * tou_llist_append	(	tou_llist_t **	elem,
		void *	dat1,
		void *	dat2,
		char	dat1_is_dynalloc,
		char	dat2_is_dynalloc )

Appends a brand new element to the list/given element and updates it in place.

Additionally, returns a pointer to the newly created element.

Parameters

[in,out]	elem	Address of the element (tou_llist_t**)
[in]	dat1	Data 1
[in]	dat2	Data 2
[in]	dat1_is_dynalloc	Should dat1 be free()'d when destroying list?
[in]	dat2_is_dynalloc	Should dat2 be free()'d when destroying list?

Returns: Pointer to the newly created element

◆ tou_llist_appendone()

tou_llist_t * tou_llist_appendone	(	tou_llist_t **	elem,
		void *	dat1,
		char	dat1_is_dynalloc )

Appends a brand new element to the list/given element which contains only dat1 and if the pointer was the head, updates it in place.

dat2 is set to a default of NULL and 0. Additionally, returns a pointer to the newly created element.

Parameters

[in,out]	elem	Address of the element (tou_llist_t**)
[in]	dat1	Data 1
[in]	dat1_is_dynalloc	Should dat1 be free()'d when destroying list?

Returns: Pointer to the newly created element

◆ tou_llist_destroy()

void tou_llist_destroy ( tou_llist_t * list )

Traverses elements using .next or .prev and frees each one including copied category string.

Parameters

[in] list Either head or tail element

◆ tou_llist_find_exact()

tou_llist_t * tou_llist_find_exact	(	tou_llist_t *	list,
		void *	dat1,
		void *	dat2 )

Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison using both parameters at the same time.

Parameters

[in]	list	Element to start the search from
[in]	dat1	Comparison value
[in]	dat2	Comparison value (if enabled)

Returns: Found element or NULL

◆ tou_llist_find_exactone()

tou_llist_t * tou_llist_find_exactone	(	tou_llist_t *	list,
		void *	dat1 )

Traverses the list starting from the passed element and tries to find the first matching element by simple equals-comparison of param.

Parameters

[in]	list	Element to start the search from
[in]	dat1	Comparison value

Returns: Found element or NULL

◆ tou_llist_find_func()

tou_llist_t * tou_llist_find_func	(	tou_llist_t *	list,
		tou_func2	cb,
		void *	userdata )

Traverses the list starting from the passed element and tries to find the first matching element by checking the return value of the given callback comparison function.

If function's return value equals 0 the element is considered matched and the search terminates, otherwise search continues.

Parameters

[in]	list	Element to start the search from
[in]	cb	Custom comparison function
[in]	userdata	Custom data to be given to the cb() function

Returns: Found element or NULL

◆ tou_llist_find_key()

tou_llist_t * tou_llist_find_key	(	tou_llist_t *	list,
		void *	dat1 )

Traverses the list starting from the passed element and tries to find the first matching element on the basis: if dat1 is not null, tries to match it as a nul-terminated string.

Parameters

[in]	list	Element to start the search from
[in]	dat1	Comparison value

Returns: Found element or NULL

◆ tou_llist_free_element()

void tou_llist_free_element ( tou_llist_t * elem )

Frees an element and its contents.

Do NOT use on an element still associated with list; use only on a tou_llist_pop'd elem for example.

Parameters

[in] elem Pointer to the element to be freed

◆ tou_llist_gather_dat1()

void ** tou_llist_gather_dat1	(	tou_llist_t *	list,
		size_t *	len )

Constructs a dynamically allocated ARRAY containing only .dat1 properties (stored as void*).

Parameters

[in]	list	Linked list to construct array from
[out]	len	Optional length of the array/llist

Returns: Void* array of .dat1's

◆ tou_llist_gather_dat2()

void ** tou_llist_gather_dat2	(	tou_llist_t *	list,
		size_t *	len )

Constructs a dynamically allocated ARRAY containing only .dat2 properties (stored as void*).

Parameters

[in]	list	Linked list to construct array from
[out]	len	Optional length of the array/llist

Returns: Void* array of .dat2's

◆ tou_llist_get_head()

tou_llist_t * tou_llist_get_head ( tou_llist_t * list )

Traverses the whole list using .next and returns the last element that was added into list (where .next is NULL)

Parameters

[in] list Element of type tou_llist_t*

Returns: Pointer to the head element

◆ tou_llist_get_newer()

tou_llist_t * tou_llist_get_newer ( tou_llist_t * elem )

Returns the element added after elem.

Returns .next of the elem.

Parameters

[in] elem Element of type tou_llist_t*

Returns: Pointer to the requested element

◆ tou_llist_get_newest()

tou_llist_t * tou_llist_get_newest ( tou_llist_t * list )

Returns the element that was added to the list last.

Alias for tou_llist_get_head.

Parameters

[in] list Element of type tou_llist_t*

Returns: Pointer to the newest element

◆ tou_llist_get_older()

tou_llist_t * tou_llist_get_older ( tou_llist_t * elem )

Returns the element added before elem.

Returns .prev of the elem.

Parameters

[in] elem Element of type tou_llist_t*

Returns: Pointer to the requested element

◆ tou_llist_get_oldest()

tou_llist_t * tou_llist_get_oldest ( tou_llist_t * list )

Returns the element that was added to the list first.

Alias for tou_llist_get_tail.

Parameters

[in] list Element of type tou_llist_t*

Returns: Pointer to the oldest element

◆ tou_llist_get_tail()

tou_llist_t * tou_llist_get_tail ( tou_llist_t * list )

Traverses the whole list using .prev and returns the first element that was added to list (where .prev is NULL)

Parameters

[in] list Element of type tou_llist_t*

Returns: Pointer to the tail element

◆ tou_llist_is_head()

char tou_llist_is_head ( tou_llist_t * elem )

Checks if element is head of the list (.next should be NULL)

Parameters

[in] elem Element to check

Returns: 1 or 0 depending on result

◆ tou_llist_is_tail()

char tou_llist_is_tail ( tou_llist_t * elem )

Checks if element is tail of the list (.prev should be NULL)

Parameters

[in] elem Element to check

Returns: 1 or 0 depending on result

◆ tou_llist_iter()

void tou_llist_iter	(	tou_llist_t *	list,
		tou_func	cb )

Iterate through and call the specified function for each element Automatically checks whether given element is head or tail and iterates accordingly.

If given function returns a 0 the iteration terminates early.

Parameters

[in]	list	Head or tail of the list
[in]	cb	Function to be called for each element

◆ tou_llist_len()

size_t tou_llist_len ( tou_llist_t * list )

Goes through the list and returns amount of elements.

Parameters

[in] list List to count elements

Returns: Number of elements

◆ tou_llist_next_newer()

tou_llist_t * tou_llist_next_newer ( tou_llist_t ** elem )

Updates elem to point to the element added after itself.

elem is updated to .next of the elem. That same .next is additionally returned from function.

Parameters

[in,out] elem Address of the element

Returns: Pointer to the element

◆ tou_llist_next_older()

tou_llist_t * tou_llist_next_older ( tou_llist_t ** elem )

Updates elem to point to the element added before itself.

elem is updated to .prev of the elem. That same .next is additionally returned from function.

Parameters

[in,out] elem Address of the element

Returns: Pointer to the element

◆ tou_llist_pop()

tou_llist_t * tou_llist_pop ( tou_llist_t * elem )

Disconnects an element from llist but does not deallocate it.

You should destroy it by calling tou_llist_free_element or manually.

Parameters

[in] elem Pointer to the element to be removed

Returns: Pointer to the element popped from llist

◆ tou_llist_prepend()

tou_llist_t * tou_llist_prepend	(	tou_llist_t **	elem,
		void *	dat1,
		void *	dat2,
		char	dat1_is_dynalloc,
		char	dat2_is_dynalloc )

Prepends a brand new element to the list/given element.

Additionally, returns a pointer to the newly created element.

Parameters

[in,out]	elem	Address of the element (tou_llist_t**)
[in]	dat1	Data 1
[in]	dat2	Data 2
[in]	dat1_is_dynalloc	Should dat1 be free()'d when destroying list?
[in]	dat2_is_dynalloc	Should dat2 be free()'d when destroying list?

Returns: Pointer to the newly created element

◆ tou_llist_prependone()

tou_llist_t * tou_llist_prependone	(	tou_llist_t **	elem,
		void *	dat1,
		char	dat1_is_dynalloc )

Prepends a brand new element to the list/given element which only contains dat1.

dat2 is set to a default of NULL and 0. Additionally, returns a pointer to the newly created element.

Parameters

[in,out]	elem	Address of the element (tou_llist_t**)
[in]	dat1	Data 1
[in]	dat1_is_dynalloc	Should dat1 be free()'d when destroying list?

Returns: Pointer to the newly created element

◆ tou_llist_remove()

tou_llist_t * tou_llist_remove ( tou_llist_t * elem )

Removes an element from llist and deallocates it.

If you were to for example remove the head you should assign the return value to something or else you will be left with an invalid pointer and a segfault because this function simply reconnects .prev and .next if they exist, and frees the element.

If elem was the head, function will return .prev to be used as the new head. Otherwise, it will return .next which may be used or ignored.

Parameters

[in] elem Pointer to the element to be removed

Returns: Element that should optionally take elem's place

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ tou_llist_new

◆ tou_llist_print

◆ tou_llist_print_tail

Function Documentation

◆ tou_llist_append()

◆ tou_llist_appendone()

◆ tou_llist_destroy()

◆ tou_llist_find_exact()

◆ tou_llist_find_exactone()

◆ tou_llist_find_func()

◆ tou_llist_find_key()

◆ tou_llist_free_element()

◆ tou_llist_gather_dat1()

◆ tou_llist_gather_dat2()

◆ tou_llist_get_head()

◆ tou_llist_get_newer()

◆ tou_llist_get_newest()

◆ tou_llist_get_older()

◆ tou_llist_get_oldest()

◆ tou_llist_get_tail()

◆ tou_llist_is_head()

◆ tou_llist_is_tail()

◆ tou_llist_iter()

◆ tou_llist_len()

◆ tou_llist_next_newer()

◆ tou_llist_next_older()

◆ tou_llist_pop()

◆ tou_llist_prepend()

◆ tou_llist_prependone()

◆ tou_llist_remove()