stbllist.h File Reference

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

#include "techtype.h"

Go to the source code of this file.

Data Structures
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