chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/csapph/h/llistMan

   1 /*
   2  * llistMan.h
   3  *
   4  * [Generated from llistMan, 25 September 1996]
   5  */
   6
   7 #if !defined(__CC_NORCROFT) || !defined(__arm)
   8   #error You must use the Norcroft ARM Compiler for Sapphire programs
   9 #endif
  10
  11 #pragma include_only_once
  12 #pragma force_top_level
  13
  14 #ifndef __llistMan_h
  15 #define __llistMan_h
  16
  17 #ifndef __sapphire_h
  18   #include "sapphire.h"
  19 #endif
  20
  21 /*----- Overview ----------------------------------------------------------*
  22  *
  23  * Functions provided:
  24  *
  25  *  llist_create
  26  *  llist_destroy
  27  *  llist_addItem
  28  *  llist_removeItem
  29  *  llist_reinsert
  30  *  llist_setFlags
  31  *  llist_items
  32  *  llist_enumerate
  33  *  llist_itemToIndex
  34  *  llist_indexToItem
  35  *  llist_registerSort
  36  *  llist_init
  37  *  llist_desc
  38  */
  39
  40 /* --- llist_create --- *
  41  *
  42  * On entry:    R0 == pointer to 12 byte list head to fill in
  43  *              R1 == sort routine to use (0 for none)
  44  *
  45  * On exit:     List head filled in appropriately
  46  *
  47  * Use:         This call set up list. It must be made just once, before
  48  *              and other list alls are made. On entry, R0 must point to
  49  *              12 bytes in memory, which is filled in by this call.
  50  *              Example code may look like:
  51  *
  52  *                      ADR     R0,myList
  53  *                      LDR     R1,=myStrCmp
  54  *                      BL      llist_create
  55  *
  56  *                        .
  57  *                         .
  58  *                        .
  59  *
  60  *                      mylist  DCD     0,0
  61  */
  62
  63 extern routine llist_create;
  64
  65 /* --- llist_destroy --- *
  66  *
  67  * On entry:    R0 == pointer to list head
  68  *
  69  * On exit:     R0 corrupted
  70  *
  71  * Use:         Destroys the given list.
  72  */
  73
  74 extern routine llist_destroy;
  75
  76 /* --- llist_addItem --- *
  77  *
  78  * On entry:    R0 == pointer to list head
  79  *              R1 == pointer to user data (or 0 if none to copy)
  80  *              R2 == size of user data
  81  *
  82  * On exit:     R0 preserved
  83  *              R1 == pointer to the new user data
  84  *              May return an error
  85  *
  86  * Use:         This call will add an item to a list. Notice that the
  87  *              item is entirely allocated by the list manager, it does not
  88  *              point to the data that you supply it, instead it
  89  *              copies the data into the newly created item. For this reason
  90  *              if 0 is supplied as the user data, nothing is copied.
  91  *              It is the returned user data pointer, that must be
  92  *              used to reference the item in other llist calls.
  93  */
  94
  95 extern routine llist_addItem;
  96
  97 /* --- llist_removeItem --- *
  98  *
  99  * On entry:    R0 == list head pointer
 100  *              R1 == pointer to item to remove (as returned by addItem)
 101  *
 102  * On exit:     --
 103  *
 104  * Use:         This call removes the item from the given list. All
 105  *              memory taken up by the item is freed. If the value
 106  *              passed in R1 is not an item in the list, then all hell is
 107  *              likely to break loose, so I don't advise making this mistake.
 108  */
 109
 110 extern routine llist_removeItem;
 111
 112 /* --- llist_reinsert --- *
 113  *
 114  * On entry:    R0 == pointer to list head
 115  *              R1 == item to reinsert
 116  *
 117  * On exit:     --
 118  *
 119  * Use:         Reinserts the given item into the list. This call is
 120  *              used if the item is updated in such a way that its
 121  *              position in the list may change.
 122  */
 123
 124 extern routine llist_reinsert;
 125
 126 /* --- llist_setFlags --- *
 127  *
 128  * On entry:    R1 == pointer to list item
 129  *              R2 == BIC word
 130  *              R3 == EOR word
 131  *
 132  * On exit:     R2 == the new flags word
 133  *
 134  * Use:         Sets the flags associated with the given item. If you
 135  *              just wish to read them, set R2 and R3 to 0.
 136  */
 137
 138 extern routine llist_setFlags;
 139
 140 /* --- llist_items --- *
 141  *
 142  * On entry:    R0 == pointer to list head
 143  *
 144  * On exit:     R1 == number of items in list
 145  *
 146  * Use:         Returns the number of items in the list given. This is
 147  *              a cached value, and so is very fast.
 148  */
 149
 150 extern routine llist_items;
 151
 152 /* --- llist_enumerate --- *
 153  *
 154  * On entry:    R0 == pointer to list head
 155  *              R1 == pointer to item (0 for first)
 156  *              R2 == mask word
 157  *              R3 == test word
 158  *
 159  * On exit:     CS and R1 == next item that matches
 160  *              CC and R1 corrupted if no more items
 161  *
 162  * Use:         This calls return each item in the list, one at a time,
 163  *              as long as the item matches the pattern given.
 164  */
 165
 166 extern routine 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
 178 extern routine llist_itemToIndex;
 179
 180 /* --- llist_indexToItem --- *
 181  *
 182  * On entry:    R0 == pointer to list head
 183  *              R1 == point to the index (indexed from 0)
 184  *
 185  * On exit:     R1 == the item itself, or 0 if index doesn't exist
 186  *
 187  * Use:         Returns the index of the item given, indexed from 0.
 188  */
 189
 190 extern routine llist_indexToItem;
 191
 192 /* --- llist_registerSort --- *
 193  *
 194  * On entry:    R0 == pointer to list head
 195  *              R1 == pointer to new sort routine
 196  *
 197  * On exit:     --
 198  *
 199  * Use:         Registers a new sort routine to be used on the given
 200  *              list. This call will also cause a complete resort
 201  *              of the given list using a mergesort algorithm -- O(n log n).
 202  */
 203
 204 extern routine llist_registerSort;
 205
 206 /* --- llist_init --- *
 207  *
 208  * On entry:    --
 209  *
 210  * On exit:     --
 211  *
 212  * Use:         Initialises the llistMan unit.
 213  */
 214
 215 extern routine llist_init;
 216
 217 /* --- llist_desc --- *
 218  *
 219  * A llist decription for use with listbox
 220  */
 221
 222 extern routine llist_desc;
 223
 224 /*----- That's all, folks -------------------------------------------------*/
 225
 226 #endif