The provided list implementation uses a generic doubly-linked approach in which each node, apart from storing its data, has two link pointers. The first link points to the previous node in the list and the second link, points to the next node in the list. The first node of the list has its previous link pointing to NULL, similarly, the last node of the list has its next node pointing to NULL. More...

Collaboration diagram for Generic double-linked lists:

Data Structures
struct	qList_Node_t
	A list-node object (Used internally) More...

struct	qList_t
	A list object (Generic double-linked) More...

struct	qList_ForEachHandle_t
	Handle of the qList_ForEach() API that is passed as an argument to the function that operates on each node. More...

struct	qList_CompareHandle_t
	Handle of the qList_Sort() API that is passed as an argument to the compare function. More...

struct	qList_Iterator_t
	Typedef to hold a list-iterator instance. More...

Macros
#define	qNode_MinimalFields
	This macro can be used to create custom data that can be used as node of a list. User should locate this macro as the first member of the custom structure.

#define	QLIST_INITIALIZER
	This macro can be used to initialize empty lists.

#define	QLIST_AT_FRONT
	This macro should be used to define the destination position of a node in front of a list.

#define	QLIST_AT_BACK
	This macro should be used to define the destination position of a node at the end of a list.

#define	QLIST_FORWARD
	This macro should be used to define the direction of travel of the list forward.

#define	QLIST_BACKWARD
	This macro should be used to define the direction of travel of the list backwards.

Typedefs
typedef qBool_t(*	qList_NodeFcn_t) (qList_ForEachHandle_t h)
	Pointer to a function that operates on every node when using the qList_ForEach() API.

typedef qINT32_t	qList_Position_t
	Typedef to hold the target position of a node in a list.

typedef qBool_t(*	qList_CompareFcn_t) (qList_CompareHandle_t h)
	Pointer to a function used by the qList_Sort() API to compare nodes of a list.

typedef qList_Node_t (	qList_Direction_t) (const qList_Node_t *const node)
	Typedef to hold the direction in which the list should be traversed.

Enumerations
enum	qList_WalkStage_t { qList_WalkInit , qList_WalkThrough , qList_WalkEnd }
	An enum to describe the ForEach stage. More...

Functions
qBool_t	qList_Initialize (qList_t *const l)
	Must be called before a list is used. This initialises all the members of the list structure.

qBool_t	qList_Insert (qList_t const l, void const node, const qList_Position_t p)
	Insert an item into the list.

qBool_t	qList_RemoveItself (void *const node)
	If the node is member of a list, the node will be removed from it.

void *	qList_Remove (qList_t const l, void const node, const qList_Position_t p)
	Remove an item from the list.

qBool_t	qList_Move (qList_t const dst, qList_t const src, const qList_Position_t p)
	Moves(or merge) the entire list pointed by src to the list pointed by dst at location specified by p. After the move operation, this function leaves empty the list pointed by src.

qBool_t	qList_IsMember (const qList_t const l, const void const node)
	Check if the node is member of the list.

void *	qList_GetFront (const qList_t *const l)
	Get a pointer to the front item of the list.

void *	qList_GetBack (const qList_t *const l)
	Get a pointer to the back item of the list.

qBool_t	qList_IsEmpty (const qList_t *const l)
	Check if the list is empty.

size_t	qList_Length (const qList_t *const l)
	Get the number of items inside the list.

qBool_t	qList_Sort (qList_t *const l, qList_CompareFcn_t f)
	Sort the double linked list using the f function to determine the order. The sorting algorithm used by this function compares pairs of adjacent nodes by calling the specified f function with pointers to them as arguments. The sort is performed only modifying node's links without data swapping, improving performance if nodes have a large storage.

qBool_t	qList_IteratorSet (qList_Iterator_t i, qList_t const l, void *nodeOffset, const qList_Direction_t d)
	Setup an instance of the given iterator to traverse the list.

qBool_t	qList_ForEach (const qList_t const l, const qList_NodeFcn_t f, void arg, qList_Direction_t d, void *nodeOffset)
	Operate on each element of the list.

qBool_t	qList_Swap (void node1, void node2)
	Swap two nodes that belongs to the same list by changing its own links.

qList_Iterator_t	qList_Begin (qList_t *const xList)
	Returns an iterator pointing to the first element in the list container.

qList_Iterator_t	qList_End (qList_t *const xList)
	Returns an iterator pointing to the last element in the list container.

qBool_t	qListIterator_Until (const qList_Iterator_t const i, const void const node)
	Check until current iterator reach the given node.

void	qListIterator_Forward (qList_Iterator_t *i)
	Move the iterator forward.

void	qListIterator_Backward (qList_Iterator_t *i)
	Move the iterator backward.

void *	qListIterator_Get (const qList_Iterator_t *const i)
	Gets the node that the iterator is currently pointing to.

Detailed Description

The provided list implementation uses a generic doubly-linked approach in which each node, apart from storing its data, has two link pointers. The first link points to the previous node in the list and the second link, points to the next node in the list. The first node of the list has its previous link pointing to NULL, similarly, the last node of the list has its next node pointing to NULL.

The list data-structure, referenced through an object of type qList_t also has a head and a tail pointer, to allow fast operations on boundary nodes.

Nodes should be an user-defined data structure of any number of members, however, they must be specially defined to be compatible with the provided APIs. All the user-defined nodes must have the qNode_MinimalFields definition on top of the structure. An example is shown below:

typedef struct {
    qNode_MinimalFields;
    int a;
    int b;
    float y;
} userdata_t;

With this special type definition on all custom data, the application writer can take advantage of this versatile data structure.

Macro Definition Documentation

◆ qNode_MinimalFields

#define qNode_MinimalFields

This macro can be used to create custom data that can be used as node of a list. User should locate this macro as the first member of the custom structure.

Example :

typedef struct {
      qNode_MinimalFields;
      int x;
      float y;
      char str[ 10 ];
} mydata_t;

Typedef Documentation

◆ qList_CompareFcn_t

typedef qBool_t(* qList_CompareFcn_t) (qList_CompareHandle_t h)

Pointer to a function used by the qList_Sort() API to compare nodes of a list.

Example :

qBool_t myNode_CompareFcn( qList_CompareHandle_t h ) {
      mydata_t *n1 = (mydata_t *)h->n1;
      mydata_t *n2 = (mydata_t *)h->n2;
      return (qBool_t)( n1->x > n2->x );
}

Parameters

[in] h The handler object containing the objects being compared.

Returns: qTrue value indicates that element pointed by node1 goes after the element pointed to by node2

◆ qList_NodeFcn_t

typedef qBool_t(* qList_NodeFcn_t) (qList_ForEachHandle_t h)

Pointer to a function that operates on every node when using the qList_ForEach() API.

Example :

qBool_t ForEach_ListExample( qList_ForEachHandle_t h ) {
      if ( qList_WalkThrough == h->stage ) {
 
      }
      else if ( qList_WalkInit == h->stage ) {
 
      }
      else if ( qList_WalkEnd == h->stage ) {
 
      }
      else {
 
      }
}

Parameters

[in] h A handle to the list iterator.

Returns: A boolean value that can be used to continue or break the walk through loop over the list. If a qTrue value its returned the break will be performed

Enumeration Type Documentation

◆ qList_WalkStage_t

enum qList_WalkStage_t

An enum to describe the ForEach stage.

Enumerator
qList_WalkInit	When the loop is about to start. In this case, A `NULL` value will be passed in the node pointer.
qList_WalkThrough	When the loop is traversing the list.
qList_WalkEnd	When the loop has finished. In this case, A `NULL` value will be passed in the node pointer.

Function Documentation

◆ qList_Begin()

qList_Iterator_t qList_Begin ( qList_t *const xList )

Returns an iterator pointing to the first element in the list container.

Parameters

[in] xList Pointer to the list.

Returns: An iterator to the beginning of the sequence container.

◆ qList_End()

qList_Iterator_t qList_End ( qList_t *const xList )

Returns an iterator pointing to the last element in the list container.

Parameters

[in] xList Pointer to the list.

Returns: An iterator to the latest item of the sequence container.

◆ qList_ForEach()

qBool_t qList_ForEach	(	const qList_t *const	l,
		const qList_NodeFcn_t	f,
		void *	arg,
		qList_Direction_t	d,
		void *	nodeOffset )

Operate on each element of the list.

Parameters

[in]	l	Pointer to the list.
[in]	f	The function to perform over the node. Should have this prototype: qBool_t Function( qList_ForEachHandle_t h )

If f returns qTrue, the walk-through loop will be terminated.

Parameters

[in]	arg	Argument passed to f
[in]	d	Direction. Use one of the following options: QLIST_FORWARD or QLIST_BACKWARD.
	nodeOffset	If available, the list walk through will start from this node. To ignore, pass `NULL`.

Returns: qTrue if the walk through was early terminated, otherwise returns qFalse.

◆ qList_GetBack()

void * qList_GetBack ( const qList_t *const l )

Get a pointer to the back item of the list.

Parameters

[in] l Pointer to the list.

Returns: A pointer to the back node. NULL if the list is empty

◆ qList_GetFront()

void * qList_GetFront ( const qList_t *const l )

Get a pointer to the front item of the list.

Parameters

[in] l Pointer to the list.

Returns: A pointer to the front node. NULL if the list is empty

◆ qList_Initialize()

qBool_t qList_Initialize ( qList_t *const l )

Must be called before a list is used. This initialises all the members of the list structure.

Parameters

[in] l Pointer to the list being initialised.

Returns: qTrue on success, qFalse otherwise.

◆ qList_Insert()

qBool_t qList_Insert	(	qList_t *const	l,
		void *const	node,
		const qList_Position_t	p )

Insert an item into the list.

Parameters

[in]	l	Pointer to the list
[in]	node	A pointer to the node to be inserted
[in]	p	The position where the node will be inserted. Could be #QLIST_ATFRONT, #QLIST_ATBACK or any other index number where the node will be inserted after.

Returns: qTrue if the item was successfully added to the list, otherwise returns qFalse

◆ qList_IsEmpty()

qBool_t qList_IsEmpty ( const qList_t *const l )

Check if the list is empty.

Parameters

[in] l Pointer to the list.

Returns: qTrue if the list is empty, qFalse if it is not.

◆ qList_IsMember()

qBool_t qList_IsMember	(	const qList_t *const	l,
		const void *const	node )

Check if the node is member of the list.

Parameters

[in]	l	Pointer to the list.
[in]	node	A pointer to the node

Returns: qTrue if the node belongs to the list, qFalse if it is not.

◆ qList_IteratorSet()

qBool_t qList_IteratorSet	(	qList_Iterator_t *	i,
		qList_t *const	l,
		void *	nodeOffset,
		const qList_Direction_t	d )

Setup an instance of the given iterator to traverse the list.

Parameters

[in]	i	Pointer to the iterator instance
[in]	l	Pointer to the list.
[in]	nodeOffset	The start offset-node. To ignore, pass `NULL`.
[in]	d	Use one of the following options: QLIST_FORWARD or QLIST_BACKWARD.

Returns: qTrue on success. Otherwise returns qFalse.

◆ qList_Length()

size_t qList_Length ( const qList_t *const l )

Get the number of items inside the list.

Parameters

[in] l Pointer to the list.

Returns: The number of items of the list.

◆ qList_Move()

qBool_t qList_Move	(	qList_t *const	dst,
		qList_t *const	src,
		const qList_Position_t	p )

Moves(or merge) the entire list pointed by src to the list pointed by dst at location specified by p. After the move operation, this function leaves empty the list pointed by src.

Parameters

[in,out]	dst	Pointer to the list where the src nodes are to be moved.
[in]	src	Pointer to the source list to be moved.
[in]	p	The position where src list will be inserted. Could be #QLIST_ATFRONT, #QLIST_ATBACK or any other index number where the list will be inserted after.

Returns: qTrue if the move operation is performed successfully, otherwise returns qFalse

◆ qList_Remove()

void * qList_Remove	(	qList_t *const	l,
		void *const	node,
		const qList_Position_t	p )

Remove an item from the list.

Parameters

[in]	l	Pointer to the list.
[in]	node	A pointer to the node to be deleted (to ignore pass `NULL` ). If the node is member or the list, use qList_RemoveItself() to avoid overhead
[in]	p	The position of the node that will be removed. Could be #QLIST_ATFRONT, #QLIST_ATBACK or any other index number.

Returns: A pointer to the removed node. NULL if removal can't be performed.

◆ qList_RemoveItself()

qBool_t qList_RemoveItself ( void *const node )

If the node is member of a list, the node will be removed from it.

Parameters

[in] node A pointer to the node.

Returns: qTrue on Success. qFalse if removal can't be performed.

◆ qList_Sort()

qBool_t qList_Sort	(	qList_t *const	l,
		qList_CompareFcn_t	f )

Sort the double linked list using the f function to determine the order. The sorting algorithm used by this function compares pairs of adjacent nodes by calling the specified f function with pointers to them as arguments. The sort is performed only modifying node's links without data swapping, improving performance if nodes have a large storage.

Note: The function modifies the content of the list by reordering its elements as defined by f.

Parameters

[in]	l	Pointer to the list.
[in]	f	Pointer to a function that compares two nodes. This function is called repeatedly by qList_Sort() to compare two nodes. It shall follow the following prototype: qBool_t CompareFcn( qList_CompareHandle_t h )

The function defines the order of the elements by returning a Boolean data, where a qTrue value indicates that element pointed by node1 goes after the element pointed to by node2.

Returns: qTrue if at least one reordering is performed over the list.

◆ qList_Swap()

qBool_t qList_Swap	(	void *	node1,
		void *	node2 )

Swap two nodes that belongs to the same list by changing its own links.

Note: The list containing nodes will be updated if any node is part of the boundaries.

Parameters

[in]	node1	Pointer to the first node.
[in]	node2	Pointer to the second node.

Returns: qTrue if the swap operation is performed. Otherwise returns qFalse.

◆ qListIterator_Backward()

void qListIterator_Backward ( qList_Iterator_t * i )

Move the iterator backward.

Parameters

[in] i Pointer to the iterator instance

◆ qListIterator_Forward()

void qListIterator_Forward ( qList_Iterator_t * i )

Move the iterator forward.

Parameters

[in] i Pointer to the iterator instance

◆ qListIterator_Get()

void * qListIterator_Get ( const qList_Iterator_t *const i )

Gets the node that the iterator is currently pointing to.

Returns: A pointer to the node currently being pointed.

◆ qListIterator_Until()

qBool_t qListIterator_Until	(	const qList_Iterator_t *const	i,
		const void *const	node )

Check until current iterator reach the given node.

Parameters

[in]	i	Pointer to the iterator instance
[in]	node	A pointer to the node you want to reach. To ignore pass `NULL` as argument.

Returns: qTrue if the iterator has reach the given node.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ qNode_MinimalFields

Typedef Documentation

◆ qList_CompareFcn_t

◆ qList_NodeFcn_t

Enumeration Type Documentation

◆ qList_WalkStage_t

Function Documentation

◆ qList_Begin()

◆ qList_End()

◆ qList_ForEach()

◆ qList_GetBack()

◆ qList_GetFront()

◆ qList_Initialize()

◆ qList_Insert()

◆ qList_IsEmpty()

◆ qList_IsMember()

◆ qList_IteratorSet()

◆ qList_Length()

◆ qList_Move()

◆ qList_Remove()

◆ qList_RemoveItself()

◆ qList_Sort()

◆ qList_Swap()

◆ qListIterator_Backward()

◆ qListIterator_Forward()

◆ qListIterator_Get()

◆ qListIterator_Until()