Linked List [Data Structure.]

Data Structures
struct	pj_list
Defines
#define	PJ_DECL_LIST_MEMBER(type)
Functions
void	pj_list_init (pj_list_type *node)
int	pj_list_empty (const pj_list_type *node)
void	pj_list_insert_before (pj_list_type *pos, pj_list_type *node)
void	pj_list_push_back (pj_list_type *list, pj_list_type *node)
void	pj_list_insert_nodes_before (pj_list_type *lst, pj_list_type *nodes)
void	pj_list_insert_after (pj_list_type *pos, pj_list_type *node)
void	pj_list_push_front (pj_list_type *list, pj_list_type *node)
void	pj_list_insert_nodes_after (pj_list_type *lst, pj_list_type *nodes)
void	pj_list_merge_first (pj_list_type *list1, pj_list_type *list2)
void	pj_list_merge_last (pj_list_type *list1, pj_list_type *list2)
void	pj_list_erase (pj_list_type *node)
pj_list_type *	pj_list_find_node (pj_list_type *list, pj_list_type *node)
pj_list_type *	pj_list_search (pj_list_type *list, void *value, int(*comp)(void *value, const pj_list_type *node))
pj_size_t	pj_list_size (const pj_list_type *list)

---

Detailed Description

List in PJLIB is implemented as doubly-linked list, and it won't require dynamic memory allocation (just as all PJLIB data structures). The list here should be viewed more like a low level C list instead of high level C++ list (which normally are easier to use but require dynamic memory allocations), therefore all caveats with C list apply here too (such as you can NOT put a node in more than one lists).

Examples

See below for examples on how to manipulate linked list:

• Example: List Manipulation
• Test: Linked List

---

Define Documentation

#define PJ_DECL_LIST_MEMBER

(

type

)

Use this macro in the start of the structure declaration to declare that the structure can be used in the linked list operation. This macro simply declares additional member prev and next to the structure.

---

Function Documentation

int pj_list_empty

(

const pj_list_type *

node

)

Check that the list is empty.

Parameters:

node

The list head.

Returns:

Non-zero if the list is empty, or zero if it is not empty.

void pj_list_erase

(

pj_list_type *

node

)

Erase the node from the list it currently belongs.

Parameters:

node

The element to be erased.

pj_list_type* pj_list_find_node	(	pj_list_type *	list,
		pj_list_type *	node
	)

Find node in the list.

Parameters:

	list	The list head.
	node	The node element to be searched.

Returns:

The node itself if it is found in the list, or NULL if it is not found in the list.

void pj_list_init

(

pj_list_type *

node

)

Initialize the list. Initially, the list will have no member, and function pj_list_empty() will always return nonzero (which indicates TRUE) for the newly initialized list.

Parameters:

node

The list head.

void pj_list_insert_after	(	pj_list_type *	pos,
		pj_list_type *	node
	)

Insert a node to the list after the specified element position.

Parameters:

	pos	The element in the list which will precede the inserted element.
	node	The element to be inserted after the position element.

Returns:

void.

Referenced by pj_list_push_front().

void pj_list_insert_before	(	pj_list_type *	pos,
		pj_list_type *	node
	)

Insert the node to the list before the specified element position.

Parameters:

	pos	The element to which the node will be inserted before.
	node	The element to be inserted.

Returns:

void.

Referenced by pj_list_push_back().

void pj_list_insert_nodes_after	(	pj_list_type *	lst,
		pj_list_type *	nodes
	)

Insert all nodes in nodes to the target list.

Parameters:

	lst	The target list.
	nodes	Nodes list.

void pj_list_insert_nodes_before	(	pj_list_type *	lst,
		pj_list_type *	nodes
	)

Inserts all nodes in nodes to the target list.

Parameters:

	lst	The target list.
	nodes	Nodes list.

void pj_list_merge_first	(	pj_list_type *	list1,
		pj_list_type *	list2
	)

Remove elements from the source list, and insert them to the destination list. The elements of the source list will occupy the front elements of the target list. Note that the node pointed by list2 itself is not considered as a node, but rather as the list descriptor, so it will not be inserted to the list1. The elements to be inserted starts at list2->next. If list2 is to be included in the operation, use pj_list_insert_nodes_before.

Parameters:

	list1	The destination list.
	list2	The source list.

Returns:

void.

void pj_list_merge_last	(	pj_list_type *	list1,
		pj_list_type *	list2
	)

Remove elements from the second list argument, and insert them to the list in the first argument. The elements from the second list will be appended to the first list. Note that the node pointed by list2 itself is not considered as a node, but rather as the list descriptor, so it will not be inserted to the list1. The elements to be inserted starts at list2->next. If list2 is to be included in the operation, use pj_list_insert_nodes_before.

Parameters:

	list1	The element in the list which will precede the inserted element.
	list2	The element in the list to be inserted.

Returns:

void.

void pj_list_push_back	(	pj_list_type *	list,
		pj_list_type *	node
	)

Insert the node to the back of the list. This is just an alias for pj_list_insert_before().

Parameters:

	list	The list.
	node	The element to be inserted.

References pj_list_insert_before().

void pj_list_push_front	(	pj_list_type *	list,
		pj_list_type *	node
	)

Insert the node to the front of the list. This is just an alias for pj_list_insert_after().

Parameters:

	list	The list.
	node	The element to be inserted.

References pj_list_insert_after().

pj_list_type* pj_list_search	(	pj_list_type *	list,
		void *	value,
		int(*)(void *value, const pj_list_type *node)	comp
	)

Search the list for the specified value, using the specified comparison function. This function iterates on nodes in the list, started with the first node, and call the user supplied comparison function until the comparison function returns ZERO.

Parameters:

	list	The list head.
	value	The user defined value to be passed in the comparison function
	comp	The comparison function, which should return ZERO to indicate that the searched value is found.

Returns:

The first node that matched, or NULL if it is not found.

pj_size_t pj_list_size

(

const pj_list_type *

list

)

Traverse the list to get the number of elements in the list.

Parameters:

list

The list head.

Returns:

Number of elements.