Doubly-Linked List Utility Functions

The doubly-linked list utility functions provide common routines for managing linked lists. More...

Classes
struct	OSRTScalarDListNode
	This structure is used to hold a single data item within the list. More...
struct	OSRTScalarDList
	This is the main list structure. More...
Functions
EXTERNRT void	rtxScalarDListInit (OSRTScalarDList *pList)
	This function initializes a doubly linked list structure.
EXTERNRT OSRTScalarDListNode *	rtxScalarDListAppendDouble (struct OSCTXT *pctxt, OSRTScalarDList *pList, OSDOUBLE value)
	This set of functions appends an item of the given scalar type to the linked list structure.
EXTERNRT OSRTScalarDListNode *	rtxScalarDListAppendNode (OSRTScalarDList *pList, OSRTScalarDListNode *pListNode)
	This function is used to append a node to the linked list.
EXTERNRT OSRTScalarDListNode *	rtxScalarDListInsertNode (OSRTScalarDList *pList, OSUINT32 index, OSRTScalarDListNode *pListNode)
	This function is used to insert a node into the linked list.
EXTERNRT OSRTScalarDListNode *	rtxScalarDListFindByIndex (const OSRTScalarDList *pList, OSUINT32 index)
	This function will return the node pointer of the indexed entry in the list.
EXTERNRT void	rtxScalarDListFreeNode (struct OSCTXT *pctxt, OSRTScalarDList *pList, OSRTScalarDListNode *node)
	This function will remove the given node from the list and free memory.
EXTERNRT void	rtxScalarDListRemove (OSRTScalarDList *pList, OSRTScalarDListNode *node)
	This function will remove the given node from the list.
EXTERNRT void	rtxScalarDListFreeNodes (struct OSCTXT *pctxt, OSRTScalarDList *pList)
	This function will free all of the dynamic memory used to hold the list node pointers.

---

Detailed Description

The doubly-linked list utility functions provide common routines for managing linked lists.

This module is identical to the rtxDList module except that the data varaibles that can be added to the lists are scalars (integer, double, float, etc.) whereas the standard rtxDList type hold pointers to more complex data items.

---

Function Documentation

EXTERNRT OSRTScalarDListNode* rtxScalarDListAppendDouble	(	struct OSCTXT *	pctxt,
		OSRTScalarDList *	pList,
		OSDOUBLE	value
	)

This set of functions appends an item of the given scalar type to the linked list structure.

Separate functions exist for all of the different supported scalar types.

Parameters:

	pctxt	A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
	pList	A pointer to a linked list structure onto which the data item will be appended.
	value	Data item to be appended to the list.

Returns:

A pointer to an allocated node structure used to link the given data value into the list.

EXTERNRT OSRTScalarDListNode* rtxScalarDListAppendNode	(	OSRTScalarDList *	pList,
		OSRTScalarDListNode *	pListNode
	)

This function is used to append a node to the linked list.

This can be used instead of a scalar value append function. It requires the user to allocate and populate the list node structure.

Parameters:

	pList	A pointer to a linked list structure onto which the list node will be appended.
	pListNode	List node structure to be appended to the list. If this memory is to be released with the standard list memory free function, then it must be allocated using the rtxMemAlloc function.

Returns:

A pointer to an allocated node structure used to link the given data value into the list. This is the node structure that was passed in.

EXTERNRT OSRTScalarDListNode* rtxScalarDListFindByIndex	(	const OSRTScalarDList *	pList,
		OSUINT32	index
	)

This function will return the node pointer of the indexed entry in the list.

Parameters:

	pList	A pointer to a linked list structure.
	index	Zero-based index into list where the specified item is located. If the list contains fewer items then the index, NULL is returned.

Returns:

A pointer to an allocated linked list node structure. To get the actual data item, the ident field must be examined to determine what type of value is stored in the union structure.

EXTERNRT void rtxScalarDListFreeNode	(	struct OSCTXT *	pctxt,
		OSRTScalarDList *	pList,
		OSRTScalarDListNode *	node
	)

This function will remove the given node from the list and free memory.

It is assumed that memory for the list node structure was allocated using the rtxMemAlloc function.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to a linked list structure.
	node	Pointer to the list node to be removed.

EXTERNRT void rtxScalarDListFreeNodes	(	struct OSCTXT *	pctxt,
		OSRTScalarDList *	pList
	)

This function will free all of the dynamic memory used to hold the list node pointers.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to a linked list structure.

EXTERNRT void rtxScalarDListInit

(

OSRTScalarDList *

pList

)

This function initializes a doubly linked list structure.

It sets the number of elements to zero and sets all internal pointer values to NULL. A doubly-linked scalar list structure is described by the OSRTScalarDList type. Nodes of the list are of type OSRTScalarDListNode.

Parameters:

pList

A pointer to a linked list structure to be initialized.

EXTERNRT OSRTScalarDListNode* rtxScalarDListInsertNode	(	OSRTScalarDList *	pList,
		OSUINT32	index,
		OSRTScalarDListNode *	pListNode
	)

This function is used to insert a node into the linked list.

Parameters:

	pList	A pointer to a linked list structure onto which the list node will be appended.
	index	Zero-based index into list where the specified node is to be inserted.
	pListNode	List node structure to be appended to the list. If this memory is to be released with the standard list memory free function, then it must be allocated using the rtxMemAlloc function.

Returns:

A pointer to an allocated node structure used to link the given data value into the list. This is the node structure that was passed in.

EXTERNRT void rtxScalarDListRemove	(	OSRTScalarDList *	pList,
		OSRTScalarDListNode *	node
	)

This function will remove the given node from the list.

Parameters:

	pList	A pointer to a linked list structure.
	node	Pointer to the list node to be removed.