Initial revision

[ssr] / StraySrc / Libraries / Sapphire / csapph / h / llistMan

/*
 * llistMan.h
 *
 * [Generated from llistMan, 25 September 1996]
 */

#if !defined(__CC_NORCROFT) || !defined(__arm)
  #error You must use the Norcroft ARM Compiler for Sapphire programs
#endif

#pragma include_only_once
#pragma force_top_level

#ifndef __llistMan_h
#define __llistMan_h

#ifndef __sapphire_h
  #include "sapphire.h"
#endif

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  llist_create
 *  llist_destroy
 *  llist_addItem
 *  llist_removeItem
 *  llist_reinsert
 *  llist_setFlags
 *  llist_items
 *  llist_enumerate
 *  llist_itemToIndex
 *  llist_indexToItem
 *  llist_registerSort
 *  llist_init
 *  llist_desc
 */

/* --- llist_create --- *
 *
 * On entry:	R0 == pointer to 12 byte list head to fill in
 *		R1 == sort routine to use (0 for none)
 *
 * On exit:	List head filled in appropriately
 *
 * Use:		This call set up list. It must be made just once, before
 *		and other list alls are made. On entry, R0 must point to
 *		12 bytes in memory, which is filled in by this call.
 *		Example code may look like:
 *
 *			ADR	R0,myList
 *			LDR	R1,=myStrCmp
 *			BL	llist_create
 *
 *			  .
 *                         .
 *			  .
 *
 * 			mylist	DCD	0,0
 */

extern routine llist_create;

/* --- llist_destroy --- *
 *
 * On entry:	R0 == pointer to list head
 *
 * On exit:	R0 corrupted
 *
 * Use:		Destroys the given list.
 */

extern routine llist_destroy;

/* --- llist_addItem --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == pointer to user data (or 0 if none to copy)
 *		R2 == size of user data
 *
 * On exit:	R0 preserved
 *		R1 == pointer to the new user data
 *		May return an error
 *
 * Use:		This call will add an item to a list. Notice that the
 *		item is entirely allocated by the list manager, it does not
 *		point to the data that you supply it, instead it
 *		copies the data into the newly created item. For this reason
 *		if 0 is supplied as the user data, nothing is copied.
 *		It is the returned user data pointer, that must be
 *		used to reference the item in other llist calls.
 */

extern routine llist_addItem;

/* --- llist_removeItem --- *
 *
 * On entry:	R0 == list head pointer
 *		R1 == pointer to item to remove (as returned by addItem)
 *
 * On exit:	--
 *
 * Use:		This call removes the item from the given list. All
 *		memory taken up by the item is freed. If the value
 *		passed in R1 is not an item in the list, then all hell is
 *		likely to break loose, so I don't advise making this mistake.
 */

extern routine llist_removeItem;

/* --- llist_reinsert --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == item to reinsert
 *
 * On exit:	--
 *
 * Use:		Reinserts the given item into the list. This call is
 *		used if the item is updated in such a way that its
 *		position in the list may change.
 */

extern routine llist_reinsert;

/* --- llist_setFlags --- *
 *
 * On entry:	R1 == pointer to list item
 *		R2 == BIC word
 *		R3 == EOR word
 *
 * On exit:	R2 == the new flags word
 *
 * Use:		Sets the flags associated with the given item. If you
 *		just wish to read them, set R2 and R3 to 0.
 */

extern routine llist_setFlags;

/* --- llist_items --- *
 *
 * On entry:	R0 == pointer to list head
 *
 * On exit:	R1 == number of items in list
 *
 * Use:		Returns the number of items in the list given. This is
 *		a cached value, and so is very fast.
 */

extern routine llist_items;

/* --- llist_enumerate --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == pointer to item (0 for first)
 *		R2 == mask word
 *		R3 == test word
 *
 * On exit:	CS and R1 == next item that matches
 *		CC and R1 corrupted if no more items
 *
 * Use:		This calls return each item in the list, one at a time,
 *		as long as the item matches the pattern given.
 */

extern routine llist_enumerate;

/* --- llist_itemToIndex --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == point to the item
 *
 * On exit:	R1 == index of the item, -1 if it's not there
 *
 * Use:		Returns the index of the item given, indexed from 0.
 */

extern routine llist_itemToIndex;

/* --- llist_indexToItem --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == point to the index (indexed from 0)
 *
 * On exit:	R1 == the item itself, or 0 if index doesn't exist
 *
 * Use:		Returns the index of the item given, indexed from 0.
 */

extern routine llist_indexToItem;

/* --- llist_registerSort --- *
 *
 * On entry:	R0 == pointer to list head
 *		R1 == pointer to new sort routine
 *
 * On exit:	--
 *
 * Use:		Registers a new sort routine to be used on the given
 *		list. This call will also cause a complete resort
 *		of the given list using a mergesort algorithm -- O(n log n).
 */

extern routine llist_registerSort;

/* --- llist_init --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Initialises the llistMan unit.
 */

extern routine llist_init;

/* --- llist_desc --- *
 *
 * A llist decription for use with listbox
 */

extern routine llist_desc;

/*----- That's all, folks -------------------------------------------------*/

#endif