Header file - Function prototypes for linked lists. More...

#include "techtype.h"

Classes
struct	LINK_LIST_PTR_BLK

struct	LINK_LIST_HEADER

Macros
#define	CREATE_LINK_LIST_HEADER(list) static LINK_LIST_HEADER list = {NULL, &list, &list}

Functions
void	STB_LLInitialiseHeader (LINK_LIST_HEADER *hdr)
	Initialise the header variables of the linked list. More...

void	STB_LLAddBlockToEnd (LINK_LIST_HEADER hdr, LINK_LIST_PTR_BLK new_blk)
	Adds the block identified by the new_blk pointer to the end of the linked list identified by the list_hdr pointer. More...

void	STB_LLAddBlockToStart (LINK_LIST_HEADER hdr, LINK_LIST_PTR_BLK new_blk)
	Adds the block identified by the new_blk pointer to the start of the linked list identified by the list_hdr pointer. More...

void	STB_LLAddBlockBefore (LINK_LIST_PTR_BLK blk, LINK_LIST_PTR_BLK new_blk)
	Adds the block identified by the new_blk pointer to the linked list before the block identified by the next_blk pointer. More...

void	STB_LLAddBlockAfter (LINK_LIST_PTR_BLK blk, LINK_LIST_PTR_BLK new_blk)
	Adds the block identified by the new_blk pointer to the linked list after the block identified by the prev_blk pointer. More...

void	STB_LLRemoveBlock (LINK_LIST_PTR_BLK *blk)
	Removes the block identified by the blk pointer from its linked list. More...

LINK_LIST_PTR_BLK *	STB_LLGetNextBlock (LINK_LIST_PTR_BLK *blk)
	Returns a pointer to the next block in the linked list, or NULL if at the end of the list. More...

LINK_LIST_PTR_BLK *	STB_LLGetPrevBlock (LINK_LIST_PTR_BLK *blk)
	Returns a pointer to the previous block in the linked list, or NULL if at the start of the list. More...

LINK_LIST_PTR_BLK *	STB_LLGetFirstBlock (LINK_LIST_HEADER *hdr)
	Returns a pointer to the first block in the linked list, identified by hdr. More...

LINK_LIST_PTR_BLK *	STB_LLGetLastBlock (LINK_LIST_HEADER *hdr)
	Returns a pointer to the last block in the linked list, identified by hdr. More...

LINK_LIST_PTR_BLK *	STB_LLGetBlock (LINK_LIST_HEADER *hdr, U16BIT num)
	Returns a pointer to the n-th block in the list. More...

U16BIT	STB_LLGetNumBlocks (LINK_LIST_HEADER *hdr)
	Counts and returns the number of blocks in a linked list. More...

BOOLEAN	STB_LLCheckBlockInList (LINK_LIST_HEADER hdr, LINK_LIST_PTR_BLK blk)
	Checks if the supplied pointer is to a block in the specified list. More...

BOOLEAN	STB_LLSort (LINK_LIST_HEADER ll_hdr, S16BIT(cmp_func)(LINK_LIST_PTR_BLK , LINK_LIST_PTR_BLK ))
	Sorts the blocks of a link list object in ascending or descending order NOTE: The order in which the blocks will be sorted is determined solely by the callback compare function NOTE: callback function must Not alter contents of linked list NOTE: STB_LLSort is NOT re-entrant – ie. It cannot be called recursively More...

Detailed Description

Header file - Function prototypes for linked lists.

Date: 06/09/2000

Function Documentation

void STB_LLAddBlockAfter	(	LINK_LIST_PTR_BLK *	prev_blk,
		LINK_LIST_PTR_BLK *	new_blk
	)

Adds the block identified by the new_blk pointer to the linked list after the block identified by the prev_blk pointer.

Parameters

prev_blk	- pointer to the block which will become previous to the new block
new_blk	- pointer to the block to be added to the list

void STB_LLAddBlockBefore	(	LINK_LIST_PTR_BLK *	next_blk,
		LINK_LIST_PTR_BLK *	new_blk
	)

Adds the block identified by the new_blk pointer to the linked list before the block identified by the next_blk pointer.

Parameters

next_blk	- pointer to the block which will become after the new block
new_blk	- pointer to the block to be added to the list

void STB_LLAddBlockToEnd	(	LINK_LIST_HEADER *	hdr,
		LINK_LIST_PTR_BLK *	new_blk
	)

Adds the block identified by the new_blk pointer to the end of the linked list identified by the list_hdr pointer.

Parameters

hdr	- pointer to the header block for the required list new_blk - pointer to the block to be added to the list

void STB_LLAddBlockToStart	(	LINK_LIST_HEADER *	hdr,
		LINK_LIST_PTR_BLK *	new_blk
	)

Adds the block identified by the new_blk pointer to the start of the linked list identified by the list_hdr pointer.

Parameters

hdr	- pointer to the header block for the required list new_blk - pointer to the block to be added to the list

BOOLEAN STB_LLCheckBlockInList	(	LINK_LIST_HEADER *	hdr,
		LINK_LIST_PTR_BLK *	blk
	)

Checks if the supplied pointer is to a block in the specified list.

Parameters

hdr	- pointer to the list header
blk	- pointer to the block to be checked

Returns: TRUE if blk found in list specified by hdr, FALSE otherwise

LINK_LIST_PTR_BLK* STB_LLGetBlock	(	LINK_LIST_HEADER *	hdr,
		U16BIT	num
	)

Returns a pointer to the n-th block in the list.

Parameters

hdr	- pointer to the list header
num	- number of the block required

Returns: pointer to the required block, or NULL if 'num' is past the end of the list

LINK_LIST_PTR_BLK* STB_LLGetFirstBlock ( LINK_LIST_HEADER * hdr )

Returns a pointer to the first block in the linked list, identified by hdr.

Parameters

hdr	- pointer to the list header

Returns: pointer to the first block in the list, or NULL if there isn't one

LINK_LIST_PTR_BLK* STB_LLGetLastBlock ( LINK_LIST_HEADER * hdr )

Returns a pointer to the last block in the linked list, identified by hdr.

Parameters

hdr	- pointer to the list header

Returns: pointer to the last block in the list, or NULL if there isn't one

LINK_LIST_PTR_BLK* STB_LLGetNextBlock ( LINK_LIST_PTR_BLK * blk )

Returns a pointer to the next block in the linked list, or NULL if at the end of the list.

Parameters

blk	- pointer to the current block in the list

Returns: pointer to the block after the current one, or NULL if there isn't one

U16BIT STB_LLGetNumBlocks ( LINK_LIST_HEADER * hdr )

Counts and returns the number of blocks in a linked list.

Parameters

hdr	- pointer to the list header

Returns: number of blocks found

LINK_LIST_PTR_BLK* STB_LLGetPrevBlock ( LINK_LIST_PTR_BLK * blk )

Returns a pointer to the previous block in the linked list, or NULL if at the start of the list.

Parameters

blk	- pointer to the current block in the list

Returns: pointer to the block before the current one, or NULL if there isn't one

void STB_LLInitialiseHeader ( LINK_LIST_HEADER * hdr )

Initialise the header variables of the linked list.

Parameters

hdr	- pointer to the header block to be initialised

Note : Header space defined but not initlaised. this function is used rather than the CREATE_LINK_LIST_HEADER macro if link list is NOT a static (and header is malloced externally to LINK_LIST_HEADER* pointer)

void STB_LLRemoveBlock ( LINK_LIST_PTR_BLK * blk )

Removes the block identified by the blk pointer from its linked list.

Parameters

blk	- pointer to the block to be removed from the list

BOOLEAN STB_LLSort	(	LINK_LIST_HEADER *	ll_hdr,
		S16BIT()(LINK_LIST_PTR_BLK , LINK_LIST_PTR_BLK *)	cmp_func
	)

Sorts the blocks of a link list object in ascending or descending order

NOTE: The order in which the blocks will be sorted is determined solely by the callback compare function NOTE: callback function must Not alter contents of linked list

NOTE: STB_LLSort is NOT re-entrant – ie. It cannot be called recursively

Parameters

ll_hdr

- pointer to the HEADER of the linked list to be sorted

cmp_func - pointer to the compare function

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK blk_1, LINK_LIST_PTR_BLK blk_2)

The callback function must take two LINK_LIST_PTR_BLK pointer to pointer params and must return an S16BIT value of:- equal to 0 – if both compare blocks are identical less than 0 – if block_1 has a lower ordinal position than block_2

greater than 0 – if block_1 has a higher ordinal position than block_2

NOTE: It is the order of the ordinal positions that determines whether

the linked list is sorted in ascending of descending order

Returns: TRUE if successful, FALSE if failed

Parameters

ll_hdr

- pointer to the HEADER of the linked list to be sorted

mp_func - pointer to the callback compare function

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK blk_1, LINK_LIST_PTR_BLK blk_2)

The callback function must take two LINK_LIST_PTR_BLK pointer to pointer params and must return an S16BIT value of:- equal to 0 – if both compare blocks are identical less than 0 – if block_1 has a lower ordinal position than block_2

greater than 0 – if block_1 has a higher ordinal position than block_2

NOTE: It is the order of the ordinal positions that determines whether

the linked list is sorted in ascending of descending order

Returns: TRUE if successful FALSE if failed

Classes

Macros

Functions

Sorts the blocks of a link list object in ascending or descending order

NOTE: STB_LLSort is NOT re-entrant – ie. It cannot be called recursively

Detailed Description

Function Documentation

Sorts the blocks of a link list object in ascending or descending order

NOTE: STB_LLSort is NOT re-entrant – ie. It cannot be called recursively

cmp_func - pointer to the compare function

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK** blk_1, LINK_LIST_PTR_BLK** blk_2)

greater than 0 – if block_1 has a higher ordinal position than block_2

the linked list is sorted in ascending of descending order

mp_func - pointer to the callback compare function

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK** blk_1, LINK_LIST_PTR_BLK** blk_2)

greater than 0 – if block_1 has a higher ordinal position than block_2

the linked list is sorted in ascending of descending order

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK blk_1, LINK_LIST_PTR_BLK blk_2)

S16BIT (*cmp_func)(LINK_LIST_PTR_BLK blk_1, LINK_LIST_PTR_BLK blk_2)