4 ; Linked List Management
6 ; © 1994-1998 Straylight
9 ;----- Licensing note -------------------------------------------------------
11 ; This file is part of Straylight's Sapphire library.
13 ; Sapphire is free software; you can redistribute it and/or modify
14 ; it under the terms of the GNU General Public License as published by
15 ; the Free Software Foundation; either version 2, or (at your option)
18 ; Sapphire is distributed in the hope that it will be useful,
19 ; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ; GNU General Public License for more details.
23 ; You should have received a copy of the GNU General Public License
24 ; along with Sapphire. If not, write to the Free Software Foundation,
25 ; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27 ;----- Overview -------------------------------------------------------------
45 [ :LNOT::DEF:llistMan__dfn
48 ; --- llist_create ---
50 ; On entry: R0 == pointer to 12 byte list head to fill in
51 ; R1 == sort routine to use (0 for none)
53 ; On exit: List head filled in appropriately
55 ; Use: This call set up list. It must be made just once, before
56 ; and other list alls are made. On entry, R0 must point to
57 ; 12 bytes in memory, which is filled in by this call.
58 ; Example code may look like:
72 ; --- llist_destroy ---
74 ; On entry: R0 == pointer to list head
76 ; On exit: R0 corrupted
78 ; Use: Destroys the given list.
82 ; --- llist_addItem ---
84 ; On entry: R0 == pointer to list head
85 ; R1 == pointer to user data (or 0 if none to copy)
86 ; R2 == size of user data
88 ; On exit: R0 preserved
89 ; R1 == pointer to the new user data
92 ; Use: This call will add an item to a list. Notice that the
93 ; item is entirely allocated by the list manager, it does not
94 ; point to the data that you supply it, instead it
95 ; copies the data into the newly created item. For this reason
96 ; if 0 is supplied as the user data, nothing is copied.
97 ; It is the returned user data pointer, that must be
98 ; used to reference the item in other llist calls.
102 ; --- llist_removeItem ---
104 ; On entry: R0 == list head pointer
105 ; R1 == pointer to item to remove (as returned by addItem)
109 ; Use: This call removes the item from the given list. All
110 ; memory taken up by the item is freed. If the value
111 ; passed in R1 is not an item in the list, then all hell is
112 ; likely to break loose, so I don't advise making this mistake.
114 IMPORT llist_removeItem
116 ; --- llist_reinsert ---
118 ; On entry: R0 == pointer to list head
119 ; R1 == item to reinsert
123 ; Use: Reinserts the given item into the list. This call is
124 ; used if the item is updated in such a way that its
125 ; position in the list may change.
127 IMPORT llist_reinsert
129 ; --- llist_setFlags ---
131 ; On entry: R1 == pointer to list item
135 ; On exit: R2 == the new flags word
137 ; Use: Sets the flags associated with the given item. If you
138 ; just wish to read them, set R2 and R3 to 0.
140 IMPORT llist_setFlags
142 ; --- llist_items ---
144 ; On entry: R0 == pointer to list head
146 ; On exit: R1 == number of items in list
148 ; Use: Returns the number of items in the list given. This is
149 ; a cached value, and so is very fast.
153 ; --- llist_enumerate ---
155 ; On entry: R0 == pointer to list head
156 ; R1 == pointer to item (0 for first)
160 ; On exit: CS and R1 == next item that matches
161 ; CC and R1 corrupted if no more items
163 ; Use: This calls return each item in the list, one at a time,
164 ; as long as the item matches the pattern given.
166 IMPORT llist_enumerate
168 ; --- llist_itemToIndex ---
170 ; On entry: R0 == pointer to list head
171 ; R1 == point to the item
173 ; On exit: R1 == index of the item, -1 if it's not there
175 ; Use: Returns the index of the item given, indexed from 0.
177 IMPORT llist_itemToIndex
179 ; --- llist_indexToItem ---
181 ; On entry: R0 == pointer to list head
182 ; R1 == point to the index (indexed from 0)
184 ; On exit: R1 == the item itself, or 0 if index doesn't exist
186 ; Use: Returns the index of the item given, indexed from 0.
188 IMPORT llist_indexToItem
190 ; --- llist_registerSort ---
192 ; On entry: R0 == pointer to list head
193 ; R1 == pointer to new sort routine
197 ; Use: Registers a new sort routine to be used on the given
198 ; list. This call will also cause a complete resort
199 ; of the given list using a mergesort algorithm -- O(n log n).
201 IMPORT llist_registerSort
209 ; Use: Initialises the llistMan unit.
215 ; A llist decription for use with listbox
221 ;----- That's all, folks ----------------------------------------------------