dlist.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "ecu/object_id.h"
#include "ecu/utils.h"

Include dependency graph for dlist.h:

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

Go to the source code of this file.

Data Structures
struct	ecu_dnode
	Single node within list. Intrusive, so user-defined types contain this node as a member. More...
struct	ecu_dlist
	Intrusive, doubly-linked list. More...
struct	ecu_dlist_iterator
	Non-const list iterator. More...
struct	ecu_dlist_citerator
	Const list iterator. More...

Macros
#define	ECU_DNODE_OBJ_UNUSED    ((void *)0)
	Convenience define for ecu_dlist_insert_before() and ecu_dlist_sort(). Pass to these functions if optional callback object is not needed.
#define	ECU_DNODE_DESTROY_UNUSED    ((void (*)(struct ecu_dnode *, ecu_object_id_t))0)
	Convenience define for ecu_dnode_ctor(). Pass this value to ecu_dnode_ctor() if a user-defined node destructor is not needed.
#define	ECU_DNODE_GET_ENTRY(ptr_, type_, member_)    ECU_CONTAINER_OF(ptr_, type_, member_)
	Retrieves user data from an intrusive ecu_dnode by converting it back into the user's node type. More...
#define	ECU_DNODE_GET_CONST_ENTRY(ptr_, type_, member_)    ECU_CONST_CONTAINER_OF(ptr_, type_, member_)
	Const-qualified version of ECU_DNODE_GET_ENTRY(). Returned node is read-only. More...
#define	ECU_DLIST_AT_FOR_EACH(var_, iter_, list_, start_)
	Iterates (for-loops) over list nodes, starting at the specified position. The specified starting node is included in the iteration, the iteration terminates after the TAIL is reached, and it is safe to remove the current node in the iteration. More...
#define	ECU_DLIST_CONST_AT_FOR_EACH(var_, citer_, list_, start_)
	Const-qualified version of ECU_DLIST_AT_FOR_EACH(). Returned nodes are read-only. More...
#define	ECU_DLIST_FOR_EACH(var_, iter_, list_)
	Iterates (for-loops) over all list nodes starting at HEAD. HEAD is not included in the iteration, the iteration terminates after the TAIL is reached, and it is safe to remove the current node in the iteration. More...
#define	ECU_DLIST_CONST_FOR_EACH(var_, citer_, list_)
	Const-qualified version of ECU_DLIST_FOR_EACH(). Returned nodes are read-only. More...

Functions
Dnode Constructors
void	ecu_dnode_ctor (struct ecu_dnode *me, void(*destroy)(struct ecu_dnode *me, ecu_object_id_t id), ecu_object_id_t id)
	Node constructor. More...
void	ecu_dnode_destroy (struct ecu_dnode *me)
	Node destructor. Removes node if it is in a list. Executes the user-defined destructor if one was supplied to ecu_dnode_ctor(). Node must be reconstructed via ecu_dnode_ctor() in order to be used again. More...
Dnode Member Functions
ecu_object_id_t	ecu_dnode_id (const struct ecu_dnode *me)
	Returns node ID. Used to identity different user-defined types stored in the same list. More...
bool	ecu_dnode_in_list (const struct ecu_dnode *me)
	Returns true if the node is in a list. False otherwise. More...
void	ecu_dnode_insert_after (struct ecu_dnode *pos, struct ecu_dnode *node)
	Inserts a node after the specified position. More...
void	ecu_dnode_insert_before (struct ecu_dnode *pos, struct ecu_dnode *node)
	Inserts a node before the specified position. More...
struct ecu_dnode *	ecu_dnode_next (struct ecu_dnode *me)
	Returns the node next to (right of) me. NULL is returned if me is the last node in the list or if me is not in a list. More...
const struct ecu_dnode *	ecu_dnode_cnext (const struct ecu_dnode *me)
	Const-qualified version of ecu_dnode_next(). Returned node is read-only. More...
struct ecu_dnode *	ecu_dnode_prev (struct ecu_dnode *me)
	Returns the node previous to (left of) me. NULL is returned if me is the first node in the list (one after HEAD) or if me is not in a list. More...
const struct ecu_dnode *	ecu_dnode_cprev (const struct ecu_dnode *me)
	Const-qualified version of ecu_dnode_prev(). Returned node is read-only. More...
void	ecu_dnode_remove (struct ecu_dnode *me)
	Removes the node from a list. It can be reused and added to another list without reconstruction. If the supplied node is not in a list, this function does nothing. More...
bool	ecu_dnode_valid (const struct ecu_dnode *me)
	Returns true if the supplied node has been constructed via ecu_dnode_ctor(). Returns false if supplied node has not been constructed or if supplied node is HEAD (ecu_dlist::head). More...
DList Constructors
void	ecu_dlist_ctor (struct ecu_dlist *me)
	List constructor. More...
void	ecu_dlist_destroy (struct ecu_dlist *me)
	List destructor. Destroys the list and all nodes within the list. All destroyed objects must be reconstructed in order to be used again. The user-supplied destroy callback for each node executes as they are destroyed. More...
DList Member Functions
struct ecu_dnode *	ecu_dlist_back (struct ecu_dlist *me)
	Returns the tail node but does not remove it. If the list is empty, NULL is returned. More...
const struct ecu_dnode *	ecu_dlist_cback (const struct ecu_dlist *me)
	Const-qualified version of ecu_dlist_back(). Returned node is read-only. More...
void	ecu_dlist_clear (struct ecu_dlist *me)
	Removes all nodes from the list. List and nodes can be reused without reconstruction. More...
bool	ecu_dlist_empty (const struct ecu_dlist *me)
	Returns true if the list is empty. False otherwise. More...
struct ecu_dnode *	ecu_dlist_front (struct ecu_dlist *me)
	Returns the front node in the list but does not remove it. If the list is empty, returns NULL. More...
const struct ecu_dnode *	ecu_dlist_cfront (const struct ecu_dlist *me)
	Const-qualified version of ecu_dlist_front(). Returned node is read-only. More...
void	ecu_dlist_insert_before (struct ecu_dlist *me, struct ecu_dnode *node, bool(*condition)(const struct ecu_dnode *node, const struct ecu_dnode *position, void *data), void *data)
	Inserts a node before the position specified by a condition function. Starting from HEAD, all nodes within the list are iterated over. Each node is passed as the position parameter to the condition function. The user returns true if the node should be inserted before this position or false to continue the iteration. This function exits as soon as the node is inserted. If the entire list is iterated over but no condition has returned true, the node is added to the back of the list. More...
void	ecu_dlist_push_back (struct ecu_dlist *me, struct ecu_dnode *node)
	Inserts node to the back of the list. More...
void	ecu_dlist_push_front (struct ecu_dlist *me, struct ecu_dnode *node)
	Inserts node to the front of the list. More...
struct ecu_dnode *	ecu_dlist_pop_back (struct ecu_dlist *me)
	Removes the tail node from the list and returns it. If the list is empty, returns NULL. More...
struct ecu_dnode *	ecu_dlist_pop_front (struct ecu_dlist *me)
	Removes the front node from the list and returns it. If the list is empty, returns NULL. More...
size_t	ecu_dlist_size (const struct ecu_dlist *me)
	Returns the number of nodes in a list. Returns 0 if the list is empty. More...
void	ecu_dlist_sort (struct ecu_dlist *me, bool(*lhs_less_than_rhs)(const struct ecu_dnode *lhs, const struct ecu_dnode *rhs, void *data), void *data)
	Merge sorts all nodes in the list. The sorting condition is defined by a user-supplied function. More...
void	ecu_dlist_swap (struct ecu_dlist *me, struct ecu_dlist *other)
	Swaps nodes between two lists. If one list is empty, the swapped list will become empty: More...
bool	ecu_dlist_valid (const struct ecu_dlist *me)
	Returns true if the supplied list has been constructed via ecu_dlist_ctor(). False otherwise. More...
Iterators
struct ecu_dnode *	ecu_dlist_iterator_at (struct ecu_dlist_iterator *me, struct ecu_dlist *list, struct ecu_dnode *start)
	Initializes iterator at the supplied starting node's position. The supplied starting node is returned. More...
struct ecu_dnode *	ecu_dlist_iterator_begin (struct ecu_dlist_iterator *me, struct ecu_dlist *list)
	Initializes iterator and returns first node in the list. Returns first user-defined node if list is not empty. Otherwise returns the same terminal node as ecu_dlist_iterator_end(). More...
struct ecu_dnode *	ecu_dlist_iterator_end (struct ecu_dlist_iterator *me)
	Returns list's terminal node, which is HEAD (ecu_dlist::head). More...
struct ecu_dnode *	ecu_dlist_iterator_next (struct ecu_dlist_iterator *me)
	Returns the next node in the iteration. More...
const struct ecu_dnode *	ecu_dlist_iterator_cat (struct ecu_dlist_citerator *me, const struct ecu_dlist *list, const struct ecu_dnode *start)
	Const-qualified version of ecu_dlist_iterator_at(). Initializes iterator at the supplied starting node's position. The supplied starting node is returned. More...
const struct ecu_dnode *	ecu_dlist_iterator_cbegin (struct ecu_dlist_citerator *me, const struct ecu_dlist *list)
	Const-qualified version of ecu_dlist_iterator_begin(). Initializes iterator and returns first node in the list. Returns first user-defined node if list is not empty. Otherwise returns the same terminal node as ecu_dlist_iterator_cend(). More...
const struct ecu_dnode *	ecu_dlist_iterator_cend (struct ecu_dlist_citerator *me)
	Const-qualified version of ecu_dlist_iterator_end(). Returns list's terminal node, which is HEAD (ecu_dlist::head). More...
const struct ecu_dnode *	ecu_dlist_iterator_cnext (struct ecu_dlist_citerator *me)
	Const-qualified version of ecu_dlist_iterator_next(). Returns the next node in the iteration. More...

Detailed Description

See dlist.h section in Sphinx documentation.

Author

Ian Ress

Version

0.1

Date

2024-04-05

Copyright

Copyright (c) 2024

Macro Definition Documentation

ECU_DLIST_AT_FOR_EACH

#define ECU_DLIST_AT_FOR_EACH	(		var_,
			iter_,
			list_,
			start_
	)

Value:

    for (struct ecu_dnode *var_ = ecu_dlist_iterator_at(iter_, list_, start_); \
         var_ != ecu_dlist_iterator_end(iter_);                                \
         var_ = ecu_dlist_iterator_next(iter_))

Iterates (for-loops) over list nodes, starting at the specified position. The specified starting node is included in the iteration, the iteration terminates after the TAIL is reached, and it is safe to remove the current node in the iteration.

Warning

Behavior is undefined if start_ is not in a list.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_dnode.
iter_	Iterator to initialize. This will be a pointer to ecu_dlist_iterator.
list_	List to iterate over. This will be a pointer to ecu_dlist.
start_	Node in list_ to start iteration at. This will be a pointer to ecu_dnode and must be within list_. This node is included in the iteration.

ECU_DLIST_CONST_AT_FOR_EACH

#define ECU_DLIST_CONST_AT_FOR_EACH	(		var_,
			citer_,
			list_,
			start_
	)

Value:

    for (const struct ecu_dnode *var_ = ecu_dlist_iterator_cat(citer_, list_, start_); \
         var_ != ecu_dlist_iterator_cend(citer_);                                      \
         var_ = ecu_dlist_iterator_cnext(citer_))

Const-qualified version of ECU_DLIST_AT_FOR_EACH(). Returned nodes are read-only.

Warning

Behavior is undefined if start_ is not in a list.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_dnode.
citer_	Iterator to initialize. This will be a pointer to ecu_dlist_citerator.
list_	List to iterate over. This will be a pointer to const ecu_dlist.
start_	Node in list_ to start iteration at. This will be a pointer to const ecu_dnode and must be within list_. This node is included in the iteration.

ECU_DLIST_CONST_FOR_EACH

#define ECU_DLIST_CONST_FOR_EACH	(		var_,
			citer_,
			list_
	)

Value:

    for (const struct ecu_dnode *var_ = ecu_dlist_iterator_cbegin(citer_, list_); \
         var_ != ecu_dlist_iterator_cend(citer_);                                 \
         var_ = ecu_dlist_iterator_cnext(citer_))

Const-qualified version of ECU_DLIST_FOR_EACH(). Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_dnode.
citer_	Iterator to initialize. This will be a pointer to ecu_dlist_citerator.
list_	List to iterate over. This will be a pointer to const ecu_dlist. The iteration will immediately exit if this list is empty.

ECU_DLIST_FOR_EACH

#define ECU_DLIST_FOR_EACH	(		var_,
			iter_,
			list_
	)

Value:

    for (struct ecu_dnode *var_ = ecu_dlist_iterator_begin(iter_, list_); \
         var_ != ecu_dlist_iterator_end(iter_);                           \
         var_ = ecu_dlist_iterator_next(iter_))

Iterates (for-loops) over all list nodes starting at HEAD. HEAD is not included in the iteration, the iteration terminates after the TAIL is reached, and it is safe to remove the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_dnode.
iter_	Iterator to initialize. This will be a pointer to ecu_dlist_iterator.
list_	List to iterate over. This will be a pointer to ecu_dlist. The iteration will immediately exit if this list is empty.

ECU_DNODE_GET_CONST_ENTRY

#define ECU_DNODE_GET_CONST_ENTRY	(		ptr_,
			type_,
			member_
	)		ECU_CONST_CONTAINER_OF(ptr_, type_, member_)

Const-qualified version of ECU_DNODE_GET_ENTRY(). Returned node is read-only.

Parameters

ptr_	Pointer to intrusive ecu_dnode. This can be pointer to const or non-const. I.e. (struct ecu_dnode *) or (const struct ecu_dnode *).
type_	User's node type containing the intrusive ecu_dnode. Do not use const specifier. I.e. (struct my_type), never (const struct my_type).
member_	Name of ecu_dnode member within user's type.

ECU_DNODE_GET_ENTRY

#define ECU_DNODE_GET_ENTRY	(		ptr_,
			type_,
			member_
	)		ECU_CONTAINER_OF(ptr_, type_, member_)

Retrieves user data from an intrusive ecu_dnode by converting it back into the user's node type.

Parameters

ptr_	Pointer to intrusive ecu_dnode. This must be pointer to non-const. I.e. (struct ecu_dnode *).
type_	User's node type containing the intrusive ecu_dnode. Do not use const specifier. I.e. (struct my_type), never (const struct my_type).
member_	Name of ecu_dnode member within user's type.

Function Documentation

ecu_dlist_back()

struct ecu_dnode* ecu_dlist_back

(

struct ecu_dlist *

me

)

Returns the tail node but does not remove it. If the list is empty, NULL is returned.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to check.

ecu_dlist_cback()

const struct ecu_dnode* ecu_dlist_cback

(

const struct ecu_dlist *

me

)

Const-qualified version of ecu_dlist_back(). Returned node is read-only.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to check.

ecu_dlist_cfront()

const struct ecu_dnode* ecu_dlist_cfront

(

const struct ecu_dlist *

me

)

Const-qualified version of ecu_dlist_front(). Returned node is read-only.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to check.

ecu_dlist_clear()

void ecu_dlist_clear

(

struct ecu_dlist *

me

)

Removes all nodes from the list. List and nodes can be reused without reconstruction.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to clear.

ecu_dlist_ctor()

void ecu_dlist_ctor

(

struct ecu_dlist *

me

)

List constructor.

Precondition

Memory already allocated for me.

Warning

me must not be an active list, otherwise behavior is undefined.

Parameters

me	List to construct. This cannot be NULL.

ecu_dlist_destroy()

void ecu_dlist_destroy

(

struct ecu_dlist *

me

)

List destructor. Destroys the list and all nodes within the list. All destroyed objects must be reconstructed in order to be used again. The user-supplied destroy callback for each node executes as they are destroyed.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Warning

Memory is not freed since ECU is meant to be used without dynamic memory allocation. If the supplied list or any nodes within the list were allocated on the heap, user must free it themselves. It is recommended to free the nodes inside the destroy callbacks passed to ecu_dnode_ctor(). The list must be freed elsewhere.

Parameters

me	List to destroy.

ecu_dlist_empty()

bool ecu_dlist_empty

(

const struct ecu_dlist *

me

)

Returns true if the list is empty. False otherwise.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Note

An empty list means the list only has HEAD (ecu_dlist::head), which is a dummy delimiter.

Parameters

me	List to check.

ecu_dlist_front()

struct ecu_dnode* ecu_dlist_front

(

struct ecu_dlist *

me

)

Returns the front node in the list but does not remove it. If the list is empty, returns NULL.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to check.

ecu_dlist_insert_before()

void ecu_dlist_insert_before	(	struct ecu_dlist *	me,
		struct ecu_dnode *	node,
		bool(*)(const struct ecu_dnode *node, const struct ecu_dnode *position, void *data)	condition,
		void *	data
	)

Inserts a node before the position specified by a condition function. Starting from HEAD, all nodes within the list are iterated over. Each node is passed as the position parameter to the condition function. The user returns true if the node should be inserted before this position or false to continue the iteration. This function exits as soon as the node is inserted. If the entire list is iterated over but no condition has returned true, the node is added to the back of the list.

Precondition

me previously constructed via call to ecu_dlist_ctor().

node previously constructed via call to ecu_dnode_ctor().

Parameters

me	List to add to.
node	Node to add. This cannot already be within a list. This cannot be HEAD (ecu_dlist::head).
condition	Mandatory function that returns true if node should be inserted before specified position. False otherwise. node will become the new TAIL if all conditions return false.
data	Optional object to pass to condition. Supply ECU_DNODE_OBJ_UNUSED if unused.

ecu_dlist_iterator_at()

struct ecu_dnode* ecu_dlist_iterator_at	(	struct ecu_dlist_iterator *	me,
		struct ecu_dlist *	list,
		struct ecu_dnode *	start
	)

Initializes iterator at the supplied starting node's position. The supplied starting node is returned.

Precondition

Memory already allocated for me

list previously constructed via call to ecu_dlist_ctor().

start node is in list.

Warning

Not meant to be used directly. Use ECU_DLIST_AT_FOR_EACH() instead.

Parameters

me	Non-const iterator to initialize.
list	List to iterate over.
start	Starting position of the iteration. This node must be within list and cannot be HEAD (ecu_dlist::head).

ecu_dlist_iterator_begin()

struct ecu_dnode* ecu_dlist_iterator_begin	(	struct ecu_dlist_iterator *	me,
		struct ecu_dlist *	list
	)

Initializes iterator and returns first node in the list. Returns first user-defined node if list is not empty. Otherwise returns the same terminal node as ecu_dlist_iterator_end().

Precondition

Memory already allocated for me

list previously constructed via call to ecu_dlist_ctor().

Warning

Not meant to be used directly. Use ECU_DLIST_FOR_EACH() instead.

Parameters

me	Non-const iterator to initialize.
list	List to iterate over.

ecu_dlist_iterator_cat()

const struct ecu_dnode* ecu_dlist_iterator_cat	(	struct ecu_dlist_citerator *	me,
		const struct ecu_dlist *	list,
		const struct ecu_dnode *	start
	)

Const-qualified version of ecu_dlist_iterator_at(). Initializes iterator at the supplied starting node's position. The supplied starting node is returned.

Precondition

Memory already allocated for me

list previously constructed via call to ecu_dlist_ctor().

start node is in list.

Warning

Not meant to be used directly. Use ECU_DLIST_CONST_AT_FOR_EACH() instead.

Parameters

me	Const iterator to initialize.
list	List to iterate over.
start	Starting position of the iteration. This node must be within list and cannot be HEAD (ecu_dlist::head).

ecu_dlist_iterator_cbegin()

const struct ecu_dnode* ecu_dlist_iterator_cbegin	(	struct ecu_dlist_citerator *	me,
		const struct ecu_dlist *	list
	)

Const-qualified version of ecu_dlist_iterator_begin(). Initializes iterator and returns first node in the list. Returns first user-defined node if list is not empty. Otherwise returns the same terminal node as ecu_dlist_iterator_cend().

Precondition

Memory already allocated for me

list previously constructed via call to ecu_dlist_ctor().

Warning

Not meant to be used directly. Use ECU_DLIST_CONST_FOR_EACH() instead.

Parameters

me	Const iterator to initialize.
list	List to iterate over.

ecu_dlist_iterator_cend()

const struct ecu_dnode* ecu_dlist_iterator_cend

(

struct ecu_dlist_citerator *

me

)

Const-qualified version of ecu_dlist_iterator_end(). Returns list's terminal node, which is HEAD (ecu_dlist::head).

Precondition

me previously initialized via call to ecu_dlist_iterator_cbegin() or ecu_dlist_iterator_cat().

Warning

The node returned by this function should never be used since it is HEAD(ecu_dlist::head) which is a dummy delimiter.

Not meant to be used directly. Use ECU_DLIST_CONST_FOR_EACH() instead.

Parameters

me	Const iterator.

ecu_dlist_iterator_cnext()

const struct ecu_dnode* ecu_dlist_iterator_cnext

(

struct ecu_dlist_citerator *

me

)

Const-qualified version of ecu_dlist_iterator_next(). Returns the next node in the iteration.

Precondition

me previously initialized via call to ecu_dlist_iterator_cbegin() or ecu_dlist_iterator_cat().

Warning

Not meant to be used directly. Use ECU_DLIST_CONST_FOR_EACH() instead.

Parameters

me	Const iterator.

ecu_dlist_iterator_end()

struct ecu_dnode* ecu_dlist_iterator_end

(

struct ecu_dlist_iterator *

me

)

Returns list's terminal node, which is HEAD (ecu_dlist::head).

Precondition

me previously initialized via call to ecu_dlist_iterator_begin().

Warning

The node returned by this function should never be used since it is HEAD(ecu_dlist::head) which is a dummy delimiter.

Not meant to be used directly. Use ECU_DLIST_FOR_EACH() instead.

Parameters

me	Non-const iterator.

ecu_dlist_iterator_next()

struct ecu_dnode* ecu_dlist_iterator_next

(

struct ecu_dlist_iterator *

me

)

Returns the next node in the iteration.

Precondition

me previously initialized via call to ecu_dlist_iterator_begin().

Warning

Not meant to be used directly. Use ECU_DLIST_FOR_EACH() instead.

Parameters

me	Non-const iterator.

ecu_dlist_pop_back()

struct ecu_dnode* ecu_dlist_pop_back

(

struct ecu_dlist *

me

)

Removes the tail node from the list and returns it. If the list is empty, returns NULL.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to pop.

ecu_dlist_pop_front()

struct ecu_dnode* ecu_dlist_pop_front

(

struct ecu_dlist *

me

)

Removes the front node from the list and returns it. If the list is empty, returns NULL.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to pop.

ecu_dlist_push_back()

void ecu_dlist_push_back	(	struct ecu_dlist *	me,
		struct ecu_dnode *	node
	)

Inserts node to the back of the list.

Precondition

me previously constructed via call to ecu_dlist_ctor().

node previously constructed via call to ecu_dnode_ctor().

Parameters

me	List to add to.
node	Node to add. This will be the new TAIL. Node cannot already be within a list. This cannot be HEAD (ecu_dlist::head).

ecu_dlist_push_front()

void ecu_dlist_push_front	(	struct ecu_dlist *	me,
		struct ecu_dnode *	node
	)

Inserts node to the front of the list.

Precondition

me previously constructed via call to ecu_dlist_ctor().

node previously constructed via call to ecu_dnode_ctor().

Parameters

me	List to add to.
node	Node to add. This cannot already be within a list. This cannot be HEAD (ecu_dlist::head).

ecu_dlist_size()

size_t ecu_dlist_size

(

const struct ecu_dlist *

me

)

Returns the number of nodes in a list. Returns 0 if the list is empty.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to check.

ecu_dlist_sort()

void ecu_dlist_sort	(	struct ecu_dlist *	me,
		bool(*)(const struct ecu_dnode *lhs, const struct ecu_dnode *rhs, void *data)	lhs_less_than_rhs,
		void *	data
	)

Merge sorts all nodes in the list. The sorting condition is defined by a user-supplied function.

Precondition

me previously constructed via call to ecu_dlist_ctor().

Parameters

me	List to sort.
lhs_less_than_rhs	Mandatory function that defines sorting condition. Return true if left node (lhs) is less than right node (rhs). Otherwise return false.
data	Optional object to pass to lhs_less_than_rhs. Supply ECU_DNODE_OBJ_UNUSED if unused.

ecu_dlist_swap()

void ecu_dlist_swap	(	struct ecu_dlist *	me,
		struct ecu_dlist *	other
	)

Swaps nodes between two lists. If one list is empty, the swapped list will become empty:

Precondition

me and other previously constructed via call to ecu_dlist_ctor().

Parameters

me	Swap this list with other. This cannot equal other.
other	Swap this list with me. This cannot equal me.

ecu_dlist_valid()

bool ecu_dlist_valid

(

const struct ecu_dlist *

me

)

Returns true if the supplied list has been constructed via ecu_dlist_ctor(). False otherwise.

Parameters

me	List to check.

ecu_dnode_cnext()

const struct ecu_dnode* ecu_dnode_cnext

(

const struct ecu_dnode *

me

)

Const-qualified version of ecu_dnode_next(). Returned node is read-only.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_cprev()

const struct ecu_dnode* ecu_dnode_cprev

(

const struct ecu_dnode *

me

)

Const-qualified version of ecu_dnode_prev(). Returned node is read-only.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_ctor()

void ecu_dnode_ctor	(	struct ecu_dnode *	me,
		void(*)(struct ecu_dnode *me, ecu_object_id_t id)	destroy,
		ecu_object_id_t	id
	)

Node constructor.

Precondition

Memory already allocated for me.

Warning

me must not be an active node within a list, otherwise behavior is undefined.

Parameters

me	Node to construct. This cannot be NULL. This cannot be HEAD (ecu_dlist::head).
destroy	Optional callback. Defines any additional cleanup needed to fully destroy this user-defined node. Do not use API calls that edit the ecu_dnode (node insert, remove, etc) within this callback. Doing so is undefined behavior. Executes when node is destroyed via ecu_dnode_destroy(). Also executes when node is in list that is destroyed via ecu_dlist_destroy(). Supply ECU_DNODE_DESTROY_UNUSED if unused.
id	Optional ID to assign to node. Used to identify different user-defined types stored in the same list. Supply ECU_OBJECT_ID_UNUSED if unused. This value must be greater than or equal to ECU_VALID_OBJECT_ID_BEGIN

ecu_dnode_destroy()

void ecu_dnode_destroy

(

struct ecu_dnode *

me

)

Node destructor. Removes node if it is in a list. Executes the user-defined destructor if one was supplied to ecu_dnode_ctor(). Node must be reconstructed via ecu_dnode_ctor() in order to be used again.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Warning

Memory is not freed since ECU is meant to be used without dynamic memory allocation. If the supplied node was allocated on the heap user must free it themselves. It is recommended to do this inside the user-defined destroy callback passed to ecu_dnode_ctor().

Parameters

me	Node to destroy. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_id()

ecu_object_id_t ecu_dnode_id

(

const struct ecu_dnode *

me

)

Returns node ID. Used to identity different user-defined types stored in the same list.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_in_list()

bool ecu_dnode_in_list

(

const struct ecu_dnode *

me

)

Returns true if the node is in a list. False otherwise.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_insert_after()

void ecu_dnode_insert_after	(	struct ecu_dnode *	pos,
		struct ecu_dnode *	node
	)

Inserts a node after the specified position.

Precondition

pos and node previously constructed via call to ecu_dnode_ctor().

Parameters

pos	Position node. Node is inserted after this position. This must be within a list and cannot be HEAD (ecu_dlist::head).
node	Node to insert in the list. This cannot already be within a list and cannot be HEAD (ecu_dlist::head).

ecu_dnode_insert_before()

void ecu_dnode_insert_before	(	struct ecu_dnode *	pos,
		struct ecu_dnode *	node
	)

Inserts a node before the specified position.

Precondition

pos and node previously constructed via call to ecu_dnode_ctor().

Parameters

pos	Position node. Node is inserted before this position. This must be within a list and cannot be HEAD (ecu_dlist::head).
node	Node to insert. This cannot already be within a list. and cannot be HEAD (ecu_dlist::head).

ecu_dnode_next()

struct ecu_dnode* ecu_dnode_next

(

struct ecu_dnode *

me

)

Returns the node next to (right of) me. NULL is returned if me is the last node in the list or if me is not in a list.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_prev()

struct ecu_dnode* ecu_dnode_prev

(

struct ecu_dnode *

me

)

Returns the node previous to (left of) me. NULL is returned if me is the first node in the list (one after HEAD) or if me is not in a list.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to check. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_remove()

void ecu_dnode_remove

(

struct ecu_dnode *

me

)

Removes the node from a list. It can be reused and added to another list without reconstruction. If the supplied node is not in a list, this function does nothing.

Precondition

me previously constructed via call to ecu_dnode_ctor().

Parameters

me	Node to remove. This cannot be HEAD (ecu_dlist::head).

ecu_dnode_valid()

bool ecu_dnode_valid

(

const struct ecu_dnode *

me

)

Returns true if the supplied node has been constructed via ecu_dnode_ctor(). Returns false if supplied node has not been constructed or if supplied node is HEAD (ecu_dlist::head).

Parameters

me	Node to check.