QccListConcatenate.3

NAME

QccListInitialize, QccListFreeNode, QccListFree, QccListCreateNode, QccListCopyNode, QccListCompareNodes, QccListFindNode, QccListLength, QccListAppendNode, QccListInsertNode, QccListSortedInsertNode, QccListRemoveNode, QccListDeleteNode, QccListMoveNode, QccListSort, QccListConcatenate, QccListPrint - linked-list routines

SYNOPSIS

#include "libQccPack.h"

void QccListInitialize(QccList *list);

void QccListFreeNode(QccListNode *node);

void QccListFree(QccList *list);

QccListNode *QccListCreateNode(int value_size, const void *value);

QccListNode *QccListCopyNode(const QccListNode *node);

int QccListCompareNodes(const QccListNode *node1, const QccListNode *node2);

QccListNode *QccListFindNode(const QccList *list, void *value);

int QccListLength(const QccList *list);

int QccListAppendNode(QccList *list, QccListNode *node);

int QccListInsertNode(QccList *list, QccListNode *insertion_point, QccListNode *node);

int QccListSortedInsertNode(QccList *list, QccListNode *node, int sort_direction, int (*compare_values)(const void *value1, const void *value2));

int QccListRemoveNode(QccList *list, QccListNode *node);

int QccListDeleteNode(QccList *list, QccListNode *node);

int QccListMoveNode(QccList *list1, QccList *list2, QccListNode *node);

int QccListSort(QccList *list, int sort_direction, int (*compare_values)(const void *value1, const void *value2));

int QccListConcatenate(QccList *list1, QccList *list2);

int QccListPrint(QccList *list, void (*print_value)(const void *value));

DESCRIPTION

The QccPack library routines provide data structures QccListNode and QccList to represent a bi-directional linked list.

DATA STRUCTURE

The QccList data structure is defined as:

typedef struct
{
QccListNode *start;
QccListNode *end;
} QccList;

The QccListNode data structure is defined as:

typedef struct QccListNodeStruct
{
int value_size;
void *value;
struct QccListNodeStruct *previous;
struct QccListNodeStruct *next;
} QccListNode;

ROUTINES

QccListInitialize() should be called before any use of a QccList structure. QccListInitialize() initializes the pointers in list to NULL.

QccListFreeNode() frees the space previously allocated via QccListCreateNode() or QccListCopyNode().

QccListFree() frees list by calling QccListFreeNode() to free each of its nodes.

QccListCreateNode() creates a new node by allocating memory of size value_size bytes. Starting from the address pointed by value, value_size bytes are copied into the newly allocated memory space. QccListCreateNode() returns a pointer to the created node on success and NULL on failure. After the creation, the content of the new node is:

value_size: the size of the allocated memory space
value: pointer to the allocated memory space
previous: NULL
next: NULL

QccListCopyNode() creates a new node by calling QccListCreateNode(), and copies the content of node to the new node. QccListCopyNode() returns a pointer to the new node on success and NULL on failure.

QccListCompareNodes() calls the ANSI C library function memcmp(3) to compare the value-field contents of node1 and node2. If the contents are identical, 0 is returned. Otherwise, a non-zero integer is returned.

QccListFindNode() calls QccListCompareNodes() to compare the content of the value pointed to by value with the value field of each node in list. If an identical node is found, the pointer to that node is returned; otherwise, NULL is returned. QccListFindNode() assumes that value points to a range of memory consistent with the value field of a QccListNode structure.

QccListLength() returns the number of nodes contained in list.

QccListAppendNode() appends node to the end of list. If node is the first node in list, the start and end pointers of list will be set to node. 0 is always returned.

QccListInsertNode() inserts node into list just before insertion_point. The calling function must ensure that node insertion_point does indeed exist in list. If insertion_point is the first node in list, the start pointer of list will be updated accordingly. 0 is always returned.

QccListSortedInsertNode() inserts node into list after a sorting operation; sort_direction can be QCCLIST_SORTASCENDING or QCCLIST_SORTDECENDING. The sorting operation ensures that all nodes before node will be smaller (greater) than node. The result is both determined by the sorting direction and the comparison function compare_values. 0 is returned on success; otherwise, 1 is returned.

QccListRemoveNode() removes node from list. If node is the first (last) node in list, the start (end) pointer will be updated. If node is the only node in list, both the start and end pointers of list will be reset to NULL. 0 is always returned.

QccListDeleteNode() deletes node from list by calling QccListRemoveNode() to remove the node and QccListFreeNode() to free the allocated memory space. 0 is returned on success; otherwise, 1 is returned.

QccListMoveNode() moves node from list1 to list2. node is first removed from list1 by a call to QccListRemoveNode(), then it is appended to the end of list2 by a call to QccListAppendNode(). 0 is returned on success; otherwise, 1 is returned.

QccListSort() recursively removes a node from list by calling QccListRemoveNode() and inserts it back to the list by calling QccListSortedInsertNode(). 0 is returned on success; otherwise, 1 is returned.

QccListConcatenate() appends list2 to the end of list1. Both the start and end pointers of list2 are then reset to NULL. 0 is always returned.

QccListPrint() prints the content of each node in list to stdout by calling function print_value. 0 is always returned.

NOTES

Except as noted above, these linked lists routines accept NULL list or node pointers, in which case these routines return immediately without generating an error or performing any operations.

AUTHOR

This man page was written by Yufei Yuan <yuanyufei@hotmail.com>.

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
DATA STRUCTURE
ROUTINES
SEE ALSO
NOTES
AUTHOR