toolbox/list.h

   1 /************************** toolbox/list.h *************************************
   2
   3         Copyright (c) 1997 A. Krall, R. Grafl, M. Gschwind, M. Probst
   4
   5         See file COPYRIGHT for information on usage and disclaimer of warranties
   6
   7         Management of doubly linked lists
   8
   9         Authors: Reinhard Grafl      EMAIL: cacao@complang.tuwien.ac.at
  10
  11         Last Change: 1996/10/03
  12
  13 *******************************************************************************/
  14
  15 #ifndef LIST_H
  16 #define LIST_H
  17
  18 typedef struct listnode {           /* structure for list element */
  19         struct listnode *next,*prev;
  20         } listnode;
  21
  22 typedef struct list {               /* structure for list head */
  23         listnode *first,*last;
  24         int nodeoffset;
  25         } list;
  26
  27
  28 void list_init (list *l, int nodeoffset);
  29
  30 void list_addlast (list *l, void *element);
  31 void list_addfirst (list *l, void *element);
  32
  33 void list_remove (list *l, void *element);
  34
  35 void *list_first (list *l);
  36 void *list_last (list *l);
  37
  38 void *list_next (list *l, void *element);
  39 void *list_prev (list *l, void *element);
  40
  41
  42 /*
  43 ---------------------- interface description -----------------------------
  44
  45 The list management with this module works like this:
  46
  47         - to be used in a list, a structure must have an element of type
  48           'listnode'.
  49
  50         - there needs to be a structure of type 'list'.
  51
  52         - the function list_init(l, nodeoffset) initializes the structure.
  53           nodeoffset is the offset of the 'listnode' from the start of the
  54           structure in bytes.
  55
  56         - The remaining functions provide inserting, removing and searching.
  57
  58 This small example aims to demonstrate correct usage:
  59
  60
  61
  62         void bsp() {
  63                 struct node {
  64                         listnode linkage;
  65                         int value;
  66                         } a,b,c, *el;
  67
  68                 list l;
  69
  70                 a.value = 7;
  71                 b.value = 9;
  72                 c.value = 11;
  73
  74                 list_init (&l, OFFSET(struct node,linkage) );
  75                 list_addlast (&l, a);
  76                 list_addlast (&l, b);
  77                 list_addlast (&l, c);
  78
  79                 e = list_first (&l);
  80                 while (e) {
  81                         printf ("Element: %d\n", e->value);
  82                         e = list_next (&l,e);
  83                         }
  84         }
  85
  86
  87         The output from this program should be:
  88                 7
  89                 9
  90                 11
  91
  92
  93
  94 The reason for the usage of 'nodeoffset' is that this way, the same node can
  95 part of different lists (there must be one 'listnode' element for every
  96 distinct list).
  97
  98 */
  99
 100 #endif