Doubly-Linked List Utility Functions

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

Classes
struct	OSRTDListNode
	This structure is used to hold a single data item within the list. More...
struct	OSRTDList
	This is the main list structure. More...
Functions
EXTERNRT void	rtxDListInit (OSRTDList *pList)
	This function initializes a doubly linked list structure.
EXTERNRT OSRTDListNode *	rtxDListAppend (struct OSCTXT *pctxt, OSRTDList *pList, void *pData)
	This function appends an item to the linked list structure.
EXTERNRT OSRTDListNode *	rtxDListAppendCharArray (struct OSCTXT *pctxt, OSRTDList *pList, size_t length, char *pData)
	This function appends an item to the linked list structure.
EXTERNRT OSRTDListNode *	rtxDListAppendNode (OSRTDList *pList, OSRTDListNode *pListNode)
	This function appends an OSRTDListNode to the linked list structure.
EXTERNRT OSRTDListNode *	rtxDListInsert (struct OSCTXT *pctxt, OSRTDList *pList, OSSIZE idx, void *pData)
	This function inserts an item into the linked list structure.
EXTERNRT OSRTDListNode *	rtxDListInsertBefore (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
	This function inserts an item into the linked list structure before the specified element.
EXTERNRT OSRTDListNode *	rtxDListInsertAfter (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
	This function inserts an item into the linked list structure after the specified element.
EXTERNRT OSRTDListNode *	rtxDListFindByIndex (const OSRTDList *pList, OSSIZE idx)
	This function will return the node pointer of the indexed entry in the list.
EXTERNRT OSRTDListNode *	rtxDListFindByData (const OSRTDList *pList, void *data)
	This function will return the node pointer of the given data item within the list or NULL if the item is not found.
EXTERNRT int	rtxDListFindIndexByData (const OSRTDList *pList, void *data)
	This function will return the index of the given data item within the list or -1 if the item is not found.
EXTERNRT void	rtxDListFreeNode (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node)
	This function will remove the given node from the list and free memory.
EXTERNRT void	rtxDListRemove (OSRTDList *pList, OSRTDListNode *node)
	This function will remove the given node from the list.
EXTERNRT void	rtxDListFreeNodes (struct OSCTXT *pctxt, OSRTDList *pList)
	This function will free all of the dynamic memory used to hold the list node pointers.
EXTERNRT void	rtxDListFreeAll (struct OSCTXT *pctxt, OSRTDList *pList)
	This function will free all of the dynamic memory used to hold the list node pointers and the data items.
EXTERNRT int	rtxDListToArray (struct OSCTXT *pctxt, OSRTDList *pList, void **ppArray, OSSIZE *pElemCount, OSSIZE elemSize)
	This function converts a doubly linked list to an array.
EXTERNRT int	rtxDListAppendArray (struct OSCTXT *pctxt, OSRTDList *pList, void *pArray, OSSIZE numElements, OSSIZE elemSize)
	This function appends pointers to items in the given array to a doubly linked list structure.
EXTERNRT int	rtxDListAppendArrayCopy (struct OSCTXT *pctxt, OSRTDList *pList, const void *pArray, OSSIZE numElements, OSSIZE elemSize)
	This function appends a copy of each item in the given array to a doubly linked list structure.
EXTERNRT int	rtxDListToUTF8Str (struct OSCTXT *pctxt, OSRTDList *pList, OSUTF8CHAR **ppstr, char sep)
	This function concatanates all of the components in the given list to form a UTF-8 string.

---

Detailed Description

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

These lists are used to model XSD list and repeating element types within the generated code. This list type contains forward and backward pointers allowing the list to be traversed in either direction.

---

Function Documentation

EXTERNRT OSRTDListNode* rtxDListAppend	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		void *	pData
	)

This function appends an item to the linked list structure.

The data item is passed into the function as a void pointer that can point to an object of any type. The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released whenever rtxMemFree is called. The pointer to the data item itself is stored in the node structure - a copy is not made.

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.
	pData	A pointer to the 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 int rtxDListAppendArray	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		void *	pArray,
		OSSIZE	numElements,
		OSSIZE	elemSize
	)

This function appends pointers to items in the given array to a doubly linked list structure.

The array is assumed to hold an array of values as opposed to pointers. The actual address of each item in the array is stored - a copy of each item is not made.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to the linked list structure onto which the array items will be appended.
	pArray	A pointer to the source array to be converted.
	numElements	The number of elements in the array.
	elemSize	The size of one element in the array. Use the sizeof() operator to pass this parameter.

Returns:

Completion status of operation: 0 (0) = success, negative return value is error.

EXTERNRT int rtxDListAppendArrayCopy	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		const void *	pArray,
		OSSIZE	numElements,
		OSSIZE	elemSize
	)

This function appends a copy of each item in the given array to a doubly linked list structure.

In this case, the rtxMemAlloc function is used to allocate memory for each item and a copy is made.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to the linked list structure onto which the array items will be appended.
	pArray	A pointer to the source array to be converted.
	numElements	The number of elements in the array.
	elemSize	The size of one element in the array. Use the sizeof() operator to pass this parameter.

Returns:

Completion status of operation: 0 (0) = success, negative return value is error.

EXTERNRT OSRTDListNode* rtxDListAppendCharArray	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		size_t	length,
		char *	pData
	)

This function appends an item to the linked list structure.

The data item is passed into the function as a void pointer that can point to an object of any type. The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released whenever rtxMemFree is called. The array passed in is copied and a pointer to the copy is stored in the list.

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.
	length	The size of the character array to be appended.
	pData	A pointer to the character array.

Returns:

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

EXTERNRT OSRTDListNode* rtxDListAppendNode	(	OSRTDList *	pList,
		OSRTDListNode *	pListNode
	)

This function appends an OSRTDListNode to the linked list structure.

The node data is a void pointer that can point to an object of any type. The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released whenever rtxMemFree is called. The pointer to the data item itself is stored in the node structure - a copy is not made.

Parameters:

	pList	A pointer to a linked list structure onto which the data item will be appended.
	pListNode	A pointer to the node 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 OSRTDListNode* rtxDListFindByData	(	const OSRTDList *	pList,
		void *	data
	)

This function will return the node pointer of the given data item within the list or NULL if the item is not found.

Parameters:

	pList	A pointer to a linked list structure.
	data	Pointer to the data item to search for. Note that comparison of pointer values is done; not the items pointed at by the pointers.

Returns:

A pointer to an allocated linked list node structure.

EXTERNRT OSRTDListNode* rtxDListFindByIndex	(	const OSRTDList *	pList,
		OSSIZE	idx
	)

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

Parameters:

	pList	A pointer to a linked list structure.
	idx	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 data member variable pointer within this structure must be dereferenced.

EXTERNRT int rtxDListFindIndexByData	(	const OSRTDList *	pList,
		void *	data
	)

This function will return the index of the given data item within the list or -1 if the item is not found.

Parameters:

	pList	A pointer to a linked list structure.
	data	Pointer to the data item to search for. Note that comparison of pointer values is done; not the items pointed at by the pointers.

Returns:

Index of item within the list or -1 if not found.

EXTERNRT void rtxDListFreeAll	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList
	)

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

In this case, it is assumed that the rtxMemAlloc function was used to allocate memory for the data items.

Parameters:

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

EXTERNRT void rtxDListFreeNode	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		OSRTDListNode *	node
	)

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

The data memory is not freed. It might be released when the rtxMemFree or rtFreeContext function is called with this context.

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 rtxDListFreeNodes	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList
	)

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

It does not free the data items because it is unknown how the memory was allocated for these items.

Parameters:

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

EXTERNRT void rtxDListInit

(

OSRTDList *

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-list structure is described by the OSRTDList type. Nodes of the list are of type OSRTDListNode.

Memory for the structures is allocated using the rtxMemAlloc run-time function and is maintained within the context structure that is a required parameter to all rtDList functions. This memory is released when rtxMemFree is called or the context is released. Unless otherwise noted, all data passed into the list functions is simply stored on the list by value (i.e. a deep-copy of the data is not done).

Parameters:

pList

A pointer to a linked list structure to be initialized.

EXTERNRT OSRTDListNode* rtxDListInsert	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		OSSIZE	idx,
		void *	pData
	)

This function inserts an item into the linked list structure.

The data item is passed into the function as a void pointer that can point to an object of any type. The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released when the rtxMemFree function is called.

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 into which the data item is to be inserted.
	idx	Zero-based index into list where the specified item is to be inserted.
	pData	A pointer to the data item to be inserted to the list.

Returns:

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

EXTERNRT OSRTDListNode* rtxDListInsertAfter	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		OSRTDListNode *	node,
		void *	pData
	)

This function inserts an item into the linked list structure after the specified element.

The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released when the rtxMemFree function is called.

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 into which the data item is to be inserted.
	node	The position in the list where the item is to be inserted. The item will be inserted after this node or added as the head element if node is null.
	pData	A pointer to the data item to be inserted to the list.

Returns:

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

EXTERNRT OSRTDListNode* rtxDListInsertBefore	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		OSRTDListNode *	node,
		void *	pData
	)

This function inserts an item into the linked list structure before the specified element.

The rtxMemAlloc function is used to allocate memory for the list node structure; therefore, all internal list memory will be released when the rtxMemFree function is called.

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 into which the data item is to be inserted.
	node	The position in the list where the item is to be inserted. The item will be inserted before this node or appended to the list if node is null.
	pData	A pointer to the data item to be inserted to the list.

Returns:

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

EXTERNRT void rtxDListRemove	(	OSRTDList *	pList,
		OSRTDListNode *	node
	)

This function will remove the given node from the list.

The node memory is not freed. It will be released when the rtxMemFree or rtFreeContext function is called with this context.

Parameters:

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

EXTERNRT int rtxDListToArray	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		void **	ppArray,
		OSSIZE *	pElemCount,
		OSSIZE	elemSize
	)

This function converts a doubly linked list to an array.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to a linked list structure.
	ppArray	A pointer to a pointer to the destination array.
	pElemCount	A pointer to the number of elements already allocated in ppArray. If pElements is NULL, or pElements is less than the number of nodes in the list, then a new array is allocated and the pointer is stored in ppArray. Memory is allocated via calls to the rtxMemAlloc function.
	elemSize	The size of one element in the array. Use the sizeof() operator to pass this parameter.

Returns:

The number of elements in the returned array.

EXTERNRT int rtxDListToUTF8Str	(	struct OSCTXT *	pctxt,
		OSRTDList *	pList,
		OSUTF8CHAR **	ppstr,
		char	sep
	)

This function concatanates all of the components in the given list to form a UTF-8 string.

The list is assumed to contain null-terminated character string components. The given separator chraacter is inserted after each list component. The rtxMemAlloc function is used to allocate memory for the output string.

Parameters:

	pctxt	A pointer to a context structure.
	pList	A pointer to the linked list structure onto which the array items will be appended.
	ppstr	A pointer to a char pointer to hold output string.
	sep	Separator character to add between string components.

Returns:

Completion status of operation: 0 (0) = success, negative return value is error.