XBinder  Version 2.9.x
Classes | Functions
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. More...
 
EXTERNRT OSRTDListNodertxDListAppend (struct OSCTXT *pctxt, OSRTDList *pList, void *pData)
 This function appends an item to the linked list structure. More...
 
EXTERNRT OSRTDListNodertxDListAppendCharArray (struct OSCTXT *pctxt, OSRTDList *pList, size_t length, char *pData)
 This function appends an item to the linked list structure. More...
 
EXTERNRT OSRTDListNodertxDListAppendNode (OSRTDList *pList, OSRTDListNode *pListNode)
 This function appends an OSRTDListNode to the linked list structure. More...
 
EXTERNRT OSRTDListNodertxDListInsert (struct OSCTXT *pctxt, OSRTDList *pList, OSSIZE idx, void *pData)
 This function inserts an item into the linked list structure. More...
 
EXTERNRT OSRTDListNodertxDListInsertBefore (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 OSRTDListNodertxDListInsertAfter (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 OSRTDListNodertxDListFindByIndex (const OSRTDList *pList, OSSIZE idx)
 This function will return the node pointer of the indexed entry in the list. More...
 
EXTERNRT OSRTDListNodertxDListFindByData (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 OSRTDListNodertxDListFindFirstData (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
pctxtA 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.
pListA pointer to a linked list structure onto which the data item will be appended.
pDataA 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
pctxtA pointer to a context structure.
pListA pointer to the linked list structure onto which the array items will be appended.
pArrayA pointer to the source array to be converted.
numElementsThe number of elements in the array.
elemSizeThe 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
pctxtA pointer to a context structure.
pListA pointer to the linked list structure onto which the array items will be appended.
pArrayA pointer to the source array to be converted.
numElementsThe number of elements in the array.
elemSizeThe 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
pctxtA 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.
pListA pointer to a linked list structure onto which the data item will be appended.
lengthThe size of the character array to be appended.
pDataA 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
pListA pointer to a linked list structure onto which the data item will be appended.
pListNodeA 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
pListA pointer to a linked list structure.
dataPointer 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
pListA pointer to a linked list structure.
idxZero-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
pListA 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
pListA pointer to a linked list structure.
dataPointer 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
pctxtA pointer to a context structure.
pListA 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
pctxtA pointer to a context structure.
pListA pointer to a linked list structure.
nodePointer 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
pctxtA pointer to a context structure.
pListA 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
pListA 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
pctxtA 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.
pListA pointer to a linked list structure into which the data item is to be inserted.
idxZero-based index into list where the specified item is to be inserted.
pDataA 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
pctxtA 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.
pListA pointer to a linked list structure into which the data item is to be inserted.
nodeThe 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.
pDataA 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
pctxtA 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.
pListA pointer to a linked list structure into which the data item is to be inserted.
nodeThe 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.
pDataA 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
pListA pointer to a linked list structure.
nodePointer 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
pctxtA pointer to a context structure.
pListA pointer to a linked list structure.
ppArrayA pointer to a pointer to the destination array.
pElemCountA 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.
elemSizeThe 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
pctxtA pointer to a context structure.
pListA pointer to a linked list structure.
ppArrayA pointer to a pointer to the array of pointers.
pElemCountA 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
pctxtA pointer to a context structure.
pListA pointer to the linked list structure onto which the array items will be appended.
ppstrA pointer to a char pointer to hold output string.
sepSeparator character to add between string components.
Returns
Completion status of operation: 0 (0) = success, negative return value is error.