ASN1C C/C++ Common Runtime  ASN1C v7.5.x
Classes | Macros | Typedefs | Functions
Doubly-Linked List Utility Functions

Classes

struct  OSRTDListNode
 
struct  OSRTDList
 
struct  OSRTDListBuf
 
struct  OSRTDListUTF8StrNode
 

Macros

#define DLISTBUF_SEG   16
 

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)
 
OSRTDListNodertxDListAppend (struct OSCTXT *pctxt, OSRTDList *pList, void *pData)
 
OSRTDListNodertxDListAppendCharArray (struct OSCTXT *pctxt, OSRTDList *pList, size_t length, char *pData)
 
OSRTDListNodertxDListAppendNode (OSRTDList *pList, OSRTDListNode *pListNode)
 
OSRTDListNodertxDListInsert (struct OSCTXT *pctxt, OSRTDList *pList, OSSIZE idx, void *pData)
 
OSRTDListNodertxDListInsertNode (OSRTDList *pList, OSSIZE idx, OSRTDListNode *pListNode)
 
OSRTDListNodertxDListInsertBefore (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
 
OSRTDListNodertxDListInsertAfter (struct OSCTXT *pctxt, OSRTDList *pList, OSRTDListNode *node, void *pData)
 
OSRTDListNodertxDListFindByIndex (const OSRTDList *pList, OSSIZE idx)
 
OSRTDListNodertxDListFindByData (const OSRTDList *pList, void *data)
 
OSRTDListNodertxDListFindFirstData (const OSRTDList *pList)
 
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 rtxDListToPointerArray (struct OSCTXT *pctxt, OSRTDList *pList, void ***ppArray, OSSIZE *pElemCount)
 
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)
 
OSRTDListNodertxDListInsertSorted (struct OSCTXT *pctxt, OSRTDList *pList, void *pData, PEqualsFunc equalsFunc, void *sortCtxt)
 
OSRTDListNodertxDListInsertNodeSorted (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

◆ rtxDListAppend()

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.

Referenced by ASN1CType::append().

◆ rtxDListAppendArray()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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.

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

◆ rtxDListInsert()

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()

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()

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()

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()

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()

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()

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.