Doubly-Linked List Utility Functions

Classes
struct	OSRTDListNode
struct	OSRTDList
struct	OSRTDListBuf
struct	OSRTDListUTF8StrNode
Typedefs
typedef struct OSRTDListNode	OSRTDListNode
typedef struct OSRTDList	OSRTDList
typedef struct OSRTDListBuf	OSRTDListBuf
typedef struct OSRTDListUTF8StrNode	OSRTDListUTF8StrNode
typedef int(*	PEqualsFunc )(const void *a, const void *b, const void *sortCtxt)
Functions
void	rtxDListInit (OSRTDList *pList)
OSRTDListNode *	rtxDListAppend (struct OSCTXT *pctxt, OSRTDList *pList, void *pData)
OSRTDListNode *	rtxDListAppendNode (OSRTDList *pList, OSRTDListNode *pListNode)
OSRTDListNode *	rtxDListInsert (struct OSCTXT *pctxt, OSRTDList *pList, OSSIZE idx, void *pData)
OSRTDListNode *	rtxDListInsertNode (OSRTDList *pList, OSSIZE idx, OSRTDListNode *pListNode)
OSRTDListNode *	rtxDListInsertBefore (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
OSRTDListNode *	rtxDListInsertAfter (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
OSRTDListNode *	rtxDListFindByIndex (const OSRTDList *pList, OSSIZE idx)
OSRTDListNode *	rtxDListFindByData (const OSRTDList *pList, void *data)
int	rtxDListFindIndexByData (const OSRTDList *pList, void *data)
void	rtxDListFreeNode (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node)
void	rtxDListRemove (OSRTDList *pList, OSRTDListNode *node)
void	rtxDListFreeNodes (struct OSCTXT *pctxt, OSRTDList *pList)
void	rtxDListFreeAll (struct OSCTXT *pctxt, OSRTDList *pList)
int	rtxDListToArray (struct OSCTXT *pctxt, OSRTDList *pList, void **ppArray, OSSIZE *pElemCount, OSSIZE elemSize)
int	rtxDListAppendArray (struct OSCTXT *pctxt, OSRTDList *pList, void *pArray, OSSIZE numElements, OSSIZE elemSize)
int	rtxDListAppendArrayCopy (struct OSCTXT *pctxt, OSRTDList *pList, const void *pArray, OSSIZE numElements, OSSIZE elemSize)
int	rtxDListToUTF8Str (struct OSCTXT *pctxt, OSRTDList *pList, OSUTF8CHAR **ppstr, char sep)
OSRTDListNode *	rtxDListInsertSorted (struct OSCTXT *pctxt, OSRTDList *pList, void *pData, PEqualsFunc equalsFunc, void *sortCtxt)
OSRTDListNode *	rtxDListInsertNodeSorted (OSRTDList *pList, OSRTDListNode *pListNode, PEqualsFunc equalsFunc, void *sortCtxt)

---

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

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.

Referenced by ASN1CType::append().

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.

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.

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.

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.

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.

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.

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.

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.

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.

Referenced by ASN1TSeqExt::ASN1TSeqExt(), ASN1TSeqOfList::ASN1TSeqOfList(), and ASN1CSeqOfList::init().

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.

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.

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.

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.

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.

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.