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

EXTERNRT OSRTDListNode *	rtxDListAppend (struct OSCTXT pctxt, OSRTDList pList, void *pData)
	This function appends an item to the linked list structure. More...

EXTERNRT OSRTDListNode *	rtxDListAppendCharArray (struct OSCTXT pctxt, OSRTDList pList, size_t length, char *pData)
	This function appends an item to the linked list structure. More...

EXTERNRT OSRTDListNode *	rtxDListAppendNode (OSRTDList pList, OSRTDListNode pListNode)
	This function appends an `OSRTDListNode` to the linked list structure. More...

EXTERNRT OSRTDListNode *	rtxDListInsert (struct OSCTXT pctxt, OSRTDList pList, OSSIZE idx, void *pData)
	This function inserts an item into the linked list structure. More...

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

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

EXTERNRT OSRTDListNode *	rtxDListFindByIndex (const OSRTDList *pList, OSSIZE idx)
	This function will return the node pointer of the indexed entry in the list. More...

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

EXTERNRT OSRTDListNode *	rtxDListFindFirstData (const OSRTDList *pList)
	This function will return the node pointer of the first non-null data item within the list or NULL if there is no node that has non-null data. More...

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

EXTERNRT void	rtxDListFreeNode (struct OSCTXT pctxt, OSRTDList pList, OSRTDListNode *node)
	This function will remove the given node from the list and free memory. More...

EXTERNRT void	rtxDListRemove (OSRTDList pList, OSRTDListNode node)
	This function will remove the given node from the list. More...

EXTERNRT void	rtxDListFreeNodes (struct OSCTXT pctxt, OSRTDList pList)
	This function will free all of the dynamic memory used to hold the list node pointers. More...

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

EXTERNRT int	rtxDListToArray (struct OSCTXT pctxt, OSRTDList pList, void *ppArray, OSSIZE pElemCount, OSSIZE elemSize)
	This function converts a doubly linked list of *T to a dynamically (or pre-allocated) array of T. More...

EXTERNRT int	rtxDListToPointerArray (struct OSCTXT pctxt, OSRTDList pList, void **ppArray, OSSIZE pElemCount)
	This function converts a doubly linked list of T to a dynamically (or pre-allocated) array of T. More...

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

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

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

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

◆ rtxDListAppend()

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.

◆ rtxDListAppendArray()

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.

◆ rtxDListAppendArrayCopy()

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.

◆ rtxDListAppendCharArray()

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.

◆ rtxDListAppendNode()

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.

◆ rtxDListFindByData()

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.

◆ rtxDListFindByIndex()

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.

◆ rtxDListFindFirstData()

EXTERNRT OSRTDListNode* rtxDListFindFirstData ( const OSRTDList * pList )

This function will return the node pointer of the first non-null data item within the list or NULL if there is no node that has non-null data.

Parameters

pList A pointer to a linked list structure.

Returns: A pointer to an allocated linked list node structure.

◆ rtxDListFindIndexByData()

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.

◆ rtxDListFreeAll()

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.

◆ rtxDListFreeNode()

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.

◆ rtxDListFreeNodes()

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.

◆ rtxDListInit()

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.

◆ rtxDListInsert()

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.

◆ rtxDListInsertAfter()

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.

◆ rtxDListInsertBefore()

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.

◆ rtxDListRemove()

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.

◆ rtxDListToArray()

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

This function converts a doubly linked list of *T to a dynamically (or pre-allocated) array of T.

The values pointed to are copied to the array. Note: if you have an array of strings to copy to, you should use rtxDListToPointerArray.

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.

◆ rtxDListToPointerArray()

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

This function converts a doubly linked list of *T to a dynamically (or pre-allocated) array of *T.

The pointers are copied from the list to the 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 array of pointers.
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.

Returns: The number of elements in the returned array.

◆ rtxDListToUTF8Str()

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.

Classes

Functions

Detailed Description

Function Documentation

◆ rtxDListAppend()

◆ rtxDListAppendArray()

◆ rtxDListAppendArrayCopy()

◆ rtxDListAppendCharArray()

◆ rtxDListAppendNode()

◆ rtxDListFindByData()

◆ rtxDListFindByIndex()

◆ rtxDListFindFirstData()

◆ rtxDListFindIndexByData()

◆ rtxDListFreeAll()

◆ rtxDListFreeNode()

◆ rtxDListFreeNodes()

◆ rtxDListInit()

◆ rtxDListInsert()

◆ rtxDListInsertAfter()

◆ rtxDListInsertBefore()

◆ rtxDListRemove()

◆ rtxDListToArray()

◆ rtxDListToPointerArray()

◆ rtxDListToUTF8Str()