;
; llistMan.sh
;
; Linked List Management
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- 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

		[	:LNOT::DEF:llistMan__dfn
		GBLL	llistMan__dfn

; --- 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

		IMPORT	llist_create

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

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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).

		IMPORT	llist_registerSort

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

		IMPORT	llist_init

; --- llist_desc ---
;
; A llist decription for use with listbox

		IMPORT	llist_desc

		]

;----- That's all, folks ----------------------------------------------------

		END