chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/llistMan

   1 ;
   2 ; llistMan.sh
   3 ;
   4 ; Linked List Management
   5 ;
   6 ; © 1994-1998 Straylight
   7 ;
   8
   9 ;----- Licensing note -------------------------------------------------------
  10 ;
  11 ; This file is part of Straylight's Sapphire library.
  12 ;
  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)
  16 ; any later version.
  17 ;
  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.
  22 ;
  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.
  26
  27 ;----- Overview -------------------------------------------------------------
  28 ;
  29 ; Functions provided:
  30 ;
  31 ;  llist_create
  32 ;  llist_destroy
  33 ;  llist_addItem
  34 ;  llist_removeItem
  35 ;  llist_reinsert
  36 ;  llist_setFlags
  37 ;  llist_items
  38 ;  llist_enumerate
  39 ;  llist_itemToIndex
  40 ;  llist_indexToItem
  41 ;  llist_registerSort
  42 ;  llist_init
  43 ;  llist_desc
  44
  45                 [       :LNOT::DEF:llistMan__dfn
  46                 GBLL    llistMan__dfn
  47
  48 ; --- llist_create ---
  49 ;
  50 ; On entry:     R0 == pointer to 12 byte list head to fill in
  51 ;               R1 == sort routine to use (0 for none)
  52 ;
  53 ; On exit:      List head filled in appropriately
  54 ;
  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:
  59 ;
  60 ;                       ADR     R0,myList
  61 ;                       LDR     R1,=myStrCmp
  62 ;                       BL      llist_create
  63 ;
  64 ;                         .
  65 ;                         .
  66 ;                         .
  67 ;
  68 ;                       mylist  DCD     0,0
  69
  70                 IMPORT  llist_create
  71
  72 ; --- llist_destroy ---
  73 ;
  74 ; On entry:     R0 == pointer to list head
  75 ;
  76 ; On exit:      R0 corrupted
  77 ;
  78 ; Use:          Destroys the given list.
  79
  80                 IMPORT  llist_destroy
  81
  82 ; --- llist_addItem ---
  83 ;
  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
  87 ;
  88 ; On exit:      R0 preserved
  89 ;               R1 == pointer to the new user data
  90 ;               May return an error
  91 ;
  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.
  99
 100                 IMPORT  llist_addItem
 101
 102 ; --- llist_removeItem ---
 103 ;
 104 ; On entry:     R0 == list head pointer
 105 ;               R1 == pointer to item to remove (as returned by addItem)
 106 ;
 107 ; On exit:      --
 108 ;
 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.
 113
 114                 IMPORT  llist_removeItem
 115
 116 ; --- llist_reinsert ---
 117 ;
 118 ; On entry:     R0 == pointer to list head
 119 ;               R1 == item to reinsert
 120 ;
 121 ; On exit:      --
 122 ;
 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.
 126
 127                 IMPORT  llist_reinsert
 128
 129 ; --- llist_setFlags ---
 130 ;
 131 ; On entry:     R1 == pointer to list item
 132 ;               R2 == BIC word
 133 ;               R3 == EOR word
 134 ;
 135 ; On exit:      R2 == the new flags word
 136 ;
 137 ; Use:          Sets the flags associated with the given item. If you
 138 ;               just wish to read them, set R2 and R3 to 0.
 139
 140                 IMPORT  llist_setFlags
 141
 142 ; --- llist_items ---
 143 ;
 144 ; On entry:     R0 == pointer to list head
 145 ;
 146 ; On exit:      R1 == number of items in list
 147 ;
 148 ; Use:          Returns the number of items in the list given. This is
 149 ;               a cached value, and so is very fast.
 150
 151                 IMPORT  llist_items
 152
 153 ; --- llist_enumerate ---
 154 ;
 155 ; On entry:     R0 == pointer to list head
 156 ;               R1 == pointer to item (0 for first)
 157 ;               R2 == mask word
 158 ;               R3 == test word
 159 ;
 160 ; On exit:      CS and R1 == next item that matches
 161 ;               CC and R1 corrupted if no more items
 162 ;
 163 ; Use:          This calls return each item in the list, one at a time,
 164 ;               as long as the item matches the pattern given.
 165
 166                 IMPORT  llist_enumerate
 167
 168 ; --- llist_itemToIndex ---
 169 ;
 170 ; On entry:     R0 == pointer to list head
 171 ;               R1 == point to the item
 172 ;
 173 ; On exit:      R1 == index of the item, -1 if it's not there
 174 ;
 175 ; Use:          Returns the index of the item given, indexed from 0.
 176
 177                 IMPORT  llist_itemToIndex
 178
 179 ; --- llist_indexToItem ---
 180 ;
 181 ; On entry:     R0 == pointer to list head
 182 ;               R1 == point to the index (indexed from 0)
 183 ;
 184 ; On exit:      R1 == the item itself, or 0 if index doesn't exist
 185 ;
 186 ; Use:          Returns the index of the item given, indexed from 0.
 187
 188                 IMPORT  llist_indexToItem
 189
 190 ; --- llist_registerSort ---
 191 ;
 192 ; On entry:     R0 == pointer to list head
 193 ;               R1 == pointer to new sort routine
 194 ;
 195 ; On exit:      --
 196 ;
 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).
 200
 201                 IMPORT  llist_registerSort
 202
 203 ; --- llist_init ---
 204 ;
 205 ; On entry:     --
 206 ;
 207 ; On exit:      --
 208 ;
 209 ; Use:          Initialises the llistMan unit.
 210
 211                 IMPORT  llist_init
 212
 213 ; --- llist_desc ---
 214 ;
 215 ; A llist decription for use with listbox
 216
 217                 IMPORT  llist_desc
 218
 219                 ]
 220
 221 ;----- That's all, folks ----------------------------------------------------
 222
 223                 END