Group PJ_LIST

group PJ_LIST

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:

Defines

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.

Functions

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.

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_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.

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.

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_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.

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.

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_list_before(pj_list_type *pos, pj_list_type *lst)

Insert a list to another list before the specified element position.

Parameters:
  • pos – The element to which the node will be inserted before.

  • lst – The list to be inserted.

void pj_list_insert_list_after(pj_list_type *pos, pj_list_type *lst)

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

Parameters:
  • pos – The element in the list which will precede the inserted list.

  • lst – The list to be inserted.

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.

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.

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.

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

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.

struct pj_list
#include <list.h>

This structure describes generic list node and list. The owner of this list must initialize the ‘value’ member to an appropriate value (typically the owner itself).

List.

Public Members

void *prev

List prev.

void *next

List next.