Organize Sets of Pointers to the same Type of Data. More...

Data Structures
struct	SPtrList
	Pointer List Data Holder. More...

Functions
void	PtrList_setReleasePointers (SPtrList *ptr_list, int release_pointers)
	Sets the `release_pointers` Flag of a List. More...

int	PtrList_isNullList (const SPtrList *ptr_list)
	Checks for a NULL_LIST. More...

void *	PtrList_getPtr (const SPtrList *ptr_list, int index)
	Returns Pointer from List With a given Index. More...

void *	PtrList_getLastPtr (const SPtrList *ptr_list)
	Returns Last Pointer in List. More...

void *	PtrList_getFirstPtr (const SPtrList *ptr_list)
	Returns First Pointer in List. More...

int	PtrList_addPtr (SPtrList ptr_list, void ptr)
	Puts a New Pointer to List. More...

void	PtrList_removePtr (SPtrList *ptr_list, int index)
	Removes a Pointer from List. More...

void	PtrList_deleteItem (SPtrList *ptr_list, int index)
	Deletes a Pointer in List. More...

void	PtrList_updateList (SPtrList *ptr_list)
	Eliminates all NULL Spaces in List. More...

void	PtrList_clearList (SPtrList *ptr_list)
	Removes the Complete Pointer List. More...

void	PtrList_copy (SPtrList ptr_list_src, SPtrList ptr_list_dst)
	Copies a Pointer List. More...

void	PtrList_reverse (SPtrList *ptr_list)
	Reverses Order of Pointer List Elements. More...

void	PtrList_sort (SPtrList *ptr_list, int offset)
	Sorts Pointer Lists. More...

void	PtrList_shellsort (SPtrList *ptr_list, int offset)
	Sorts Pointer Lists using the Shell Sort Algorithm. More...

void	PtrList_heapsort (SPtrList *ptr_list, int offset)
	Sorts Pointer Lists using the Heap Sort Algorithm. More...

void	PtrList_print (SPtrList *pLst)
	Prints Contents of a Pointer List. More...

I32	PtrList_split (SPtrList pLstToSplit, SPtrList pLstMinor, SPtrList *pLstMajor, I32 i32MajorFirstIdx)
	Splits Up a Pointer List Into Two. More...

I32	PtrListPtr_move (SPtrList pLstFrom, SPtrList pLstTo, I32 i32Idx)
	Moves a Pointer from a List to Another. More...

void	PtrList_shuffle (const SPtrList *ptr_list, I32 SwapCount)
	Shuffles Pointers at a List. More...

Variables
const SPtrList	NULL_LIST
	NULL_LIST.

Detailed Description

The routines in this section handle a list of pointers (stored as an array of pointers) for various applications. Memory for the pointer list is allocated and released automatically. It is also possible to consider the pointers in the list as pointers to a memory block which should be released when the pointer is removed from the list or the list is erased as a whole.

A pointer list has the following Behaviour:

An empty pointer list contains no elements, the size counter is 0.
Adding a pointer increments the size counter by one.
The functions for the pointer lists contain automatic allocation for pointer memory. A small pointer list requires MIN_ALLOC words. If the space is not sufficient twice the amount of the previously allocated pointer memory will be allocated.
As soon as the list becomes empty memory space for the pointers will be released.
One can set the do_release_pointers flag to 1 for comfortable deallocation of the memory to which the pointers point to.

Usage is as follows:

Every SPtrList must be first set to the NULL_LIST.
Decide if memory pointed to by the pointers in the list should be kept or released when the pointer or the whole list is removed. Call PtrList_setReleasePointers() to set the appropriate mode.
Do – for example – some of the following tasks:
- Check if the SPtrList contains no Elements by calling isNullList().
- Add/Remove/Delete Pointers to the SPtrList by calling the appropriate functions PtrList_addPtr()/PtrList_removePtr()/PtrList_deleteItem().
- Sort SPtrList by calling PtrList_sort().
- Get First/Index/Last Pointer of the List by calling PtrList_getFirstPtr()/PtrList_getPtr()/PtrList_getLastPtr().

Data Structure Documentation

◆ SPtrList

struct SPtrList

This structure manages pointer lists.

Data Fields
void **	data	List of Pointers.
int	reserved	Only for Internal Use.
volatile int	size	Count of Pointers stored in List.
int	do_release_pointers	Deallocates Pointers Automatically If Set (See Text).

Function Documentation

◆ PtrList_setReleasePointers()

void PtrList_setReleasePointers	(	SPtrList *	ptr_list,
		int	release_pointers
	)

This function sets the release_pointers flag of a list. If the flag is set to 1, automatic deallocation of the memory being pointed to by the pointers in the list is performed whenever the pointers themselves are deleted or released.

Parameters

ptr_list	The Pointer List.
release_pointers	New Value for the `release_pointers` Flag (0 or 1).

◆ PtrList_isNullList()

int PtrList_isNullList ( const SPtrList * ptr_list )

This function checks if the list is empty.

Parameters

ptr_list The Pointer List.

◆ PtrList_getPtr()

void* PtrList_getPtr	(	const SPtrList *	ptr_list,
		int	index
	)

This function returns the pointer of a list specified by an index value.

Parameters

ptr_list	The Pointer List.
index	Index of the Pointer to be Returned.

◆ PtrList_getLastPtr()

void* PtrList_getLastPtr ( const SPtrList * ptr_list )

This function returns the last pointer in the list.

Parameters

ptr_list The Pointer List.

◆ PtrList_getFirstPtr()

void* PtrList_getFirstPtr ( const SPtrList * ptr_list )

This function returns the first pointer in the list.

Parameters

ptr_list The Pointer List.

Return values

firstPtr The first Pointer, or NULL if List is empty.

◆ PtrList_addPtr()

int PtrList_addPtr	(	SPtrList *	ptr_list,
		void *	ptr
	)

This functions puts the new pointer (ptr) at the end of the list. If the list is empty or full, additional space is allocated with the function PtrList_realloc().

Parameters

ptr_list	The Pointer List.
ptr	The Pointer to be Added as last list element.

Return values

-3	if out of memory
0	if successful

◆ PtrList_removePtr()

void PtrList_removePtr	(	SPtrList *	ptr_list,
		int	index
	)

This functions removes a pointer from the list. The function also deallocates memory at the location of the removed pointer if ptr_list->do_release_pointers=1 If the list is empty, memory for the list is released. The remaining pointers are copied to a lower location to close the gap.

Parameters

ptr_list	The Pointer List.
index	Index of the Pointer to be Removed.

◆ PtrList_deleteItem()

void PtrList_deleteItem	(	SPtrList *	ptr_list,
		int	index
	)

This function deletes a pointer in the list by just writing NULL into the pointer list. Be sure to call function PtrList_updateList() to eliminate the NULL spaces before proceeding with another function like checking the size with ptr_list->size. The function also deallocates memory at the location of the removed pointer if ptr_list->do_release_pointers=1.

Warning: Using with PtrList_getFirstPtr() may be wrong, if you have a loop over the pointer list entries and get the pointers via the getFirstPtr-routine, since this would give you the first pointer, which is still there, but NULL; you'd want to replace it by the function PtrList_getPtr().

Parameters

ptr_list	The Pointer List.
index	Index of the Pointer to be Deleted.

◆ PtrList_updateList()

void PtrList_updateList ( SPtrList * ptr_list )

This function removes all the NULL spaces in the pointer list written by function PtrList_deleteItem(). If the list turns out to be empty afterwards, memory for the list is released.

Parameters

ptr_list The Pointer List to Be Packed.

◆ PtrList_clearList()

void PtrList_clearList ( SPtrList * ptr_list )

Erases a complete pointer list, releases all memory and also the memory pointed to by pointers if requested if ptr_list-> do_release_pointers = 1.

Parameters

ptr_list The Pointer List to Be Removed.

◆ PtrList_copy()

void PtrList_copy	(	SPtrList *	ptr_list_src,
		SPtrList *	ptr_list_dst
	)

This function copies a pointer list to a previously empty pointer list.

Parameters

ptr_list_src	Source Pointer List.
ptr_list_dst	Destination Pointer List.

◆ PtrList_reverse()

void PtrList_reverse ( SPtrList * ptr_list )

This function reverses the order of the pointer list i.e., the first pointer element will be the last, etc.

Parameters

ptr_list Pointer List to Be Reversed.

◆ PtrList_sort()

void PtrList_sort	(	SPtrList *	ptr_list,
		int	offset
	)

This function sorts a given SPtrList either by using the heap or shell sort algorithm depending on the entry count of the list: For lists having less than 100 entries, the shell sort algorithm will be used, heap sort otherwise. The parameter offset is used to specify one of the struct elements for the sorting procedure. The sorting is only possible for I32 values

The sorting is performed in ascending order if offset is positive and descending for negative values of offset. For an offset value of 0 the order is ascending; however the function PtrList_reverse can be used to reverse the order afterwards.

Parameters

ptr_list	The Target.
offset	((I32)ptr + `abs(offset)`) will be Compared.

◆ PtrList_shellsort()

void PtrList_shellsort	(	SPtrList *	ptr_list,
		int	offset
	)

This function sorts a given SPtrList by using the so-called shell sort algorithm. To be more specific, the implementation is based on Knuth's suggestions. Knuth choses Increments of values $inc = (3^k - 1)/2, k \in N$ .

The sorting is performed in ascending order. If descending order is required, use the PtrList_reverse() function afterwards.

Parameters

ptr_list	The Target.
offset	((I32)ptr + `offset`) will be compared.

◆ PtrList_heapsort()

void PtrList_heapsort	(	SPtrList *	ptr_list,
		I32	offset
	)

This function sorts a given SPtrList by using the heap sort algorithm. This version of heapsort runs in 1.5n*log(n) and is recommended for all lists with count > 100

The sorting is performed in ascending order. If descending order is required, use the PtrList_reverse() function afterwards.

Parameters

ptr_list	The Target.
offset	((I32)ptr + `offset`) will be Compared.

◆ PtrList_print()

void PtrList_print ( SPtrList * pLst )

This function prints the pointers of a pointer list.

Parameters

pLst	The Pointer List to be print out.

◆ PtrList_split()

I32 PtrList_split	(	SPtrList *	pLstToSplit,
		SPtrList *	pLstMinor,
		SPtrList *	pLstMajor,
		I32	i32MajorFirstIdx
	)

This function splits the pointer list pLstToSplit into the two pointer lists pLstMinor and pLstMajor depending on the index given.

On success the source pointer list pLstToSplit contains no elements anymore. Note that the do_release_pointers setting will be transferred to each of the split up candidates.

You are free to use the pLstToSplit pointer also as pLstMinor or pLstMajor.

Parameters

pLstToSplit	The Pointer List to be split up (will be empty afterwards).
pLstMinor	The Pointer List with elements of index 0 - `i32MajorFirstIdx` (may be empty).
pLstMajor	The Pointer List with elements of index `i32MajorFirstIdx` - `pLstToSplit`->`size`-1 (may be empty).
i32MajorFirstIdx	The first Index found at the `pLstMajor` List.

Return values

ERR_BOUNDS	if `i32MajorFirstIdx` < 0 or `i32MajorFirstIdx` > `pLstToSplit`->`size`.
ERR_NONE	on Success.
PtrListPtr_move()	return value.

◆ PtrListPtr_move()

I32 PtrListPtr_move	(	SPtrList *	pLstFrom,
		SPtrList *	pLstTo,
		I32	i32Idx
	)

This function moves a pointer from a list to another by copying the pointer to the second list and writing NULL into the first list.

Warning: Be sure to call function PtrList_updateList() for the first list to eliminate the NULL spaces before proceeding with another function like checking the size with ptr_list->size.

Parameters

pLstFrom	The Pointer List to be moved from.
pLstTo	The Pointer List to be moved to.
i32Idx	The Index of the Pointer to be Moved.

Return values

ERR_PARAM	if `i32Idx` is out of Range or `pLstFrom`->`size` is 0.
ERR_INCONS	if `pLstFrom`->`do_release_pointers` differs from `pLstTo`->`do_release_pointers`.
ERR_MEMORY	if PtrList_addPtr() fails.
ERR_NONE	on Success.

◆ PtrList_shuffle()

void PtrList_shuffle	(	const SPtrList *	ptr_list,
		I32	SwapCount
	)

This function shuffles the order of the pointers at a given list by swapping two pointers from the list subsequently. The SwapCount parameter instructs the routine how many pointer swaps to be done.

Parameters

ptr_list	The Pointer List to be shuffled.
SwapCount	Count of Swaps to be Done.

Pointer Lists (SPtrList)

Data Structures

Functions

Variables

Detailed Description

Data Structure Documentation

◆ SPtrList

Function Documentation

◆ PtrList_setReleasePointers()

◆ PtrList_isNullList()

◆ PtrList_getPtr()

◆ PtrList_getLastPtr()

◆ PtrList_getFirstPtr()

◆ PtrList_addPtr()

◆ PtrList_removePtr()

◆ PtrList_deleteItem()

◆ PtrList_updateList()

◆ PtrList_clearList()

◆ PtrList_copy()

◆ PtrList_reverse()

◆ PtrList_sort()

◆ PtrList_shellsort()

◆ PtrList_heapsort()

◆ PtrList_print()

◆ PtrList_split()

◆ PtrListPtr_move()

◆ PtrList_shuffle()