src/toolbox/chain.h

   1 /************************* toolbox/chain.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 with external linking
   8
   9         Authors: Reinhard Grafl      EMAIL: cacao@complang.tuwien.ac.at
  10
  11         Last Change: 1996/10/03
  12
  13 *******************************************************************************/
  14
  15 #ifndef CHAIN_H
  16 #define CHAIN_H
  17
  18 typedef struct chainlink {          /* structure for list element */
  19         struct chainlink *next,*prev;
  20         void *element;
  21         } chainlink;
  22
  23 typedef struct chain {              /* structure for list */
  24         int  usedump;
  25
  26         chainlink *first,*last;
  27         chainlink *active;
  28         } chain;
  29
  30
  31 chain *chain_new ();
  32 chain *chain_dnew ();
  33 void chain_free(chain *c);
  34
  35 void chain_addafter(chain *c, void *element);
  36 void chain_addbefore(chain *c, void *element);
  37 void chain_addlast (chain *c, void *element);
  38 void chain_addfirst (chain *c, void *element);
  39
  40 void chain_remove(chain *c);
  41 void *chain_remove_go_prev(chain *c);
  42 void chain_removespecific(chain *c, void *element);
  43
  44 void *chain_next(chain *c);
  45 void *chain_prev(chain *c);
  46 void *chain_this(chain *c);
  47
  48 void *chain_first(chain *c);
  49 void *chain_last(chain *c);
  50
  51
  52 /*
  53 --------------------------- interface description ------------------------
  54
  55 Usage of these functions for list management is possible without additional
  56 preparation in the element structures, as opposed to the module 'list'.
  57
  58 Consequently, the functions are a little slower and need more memory.
  59
  60 A new list is created with
  61         chain_new
  62 or  chain_dnew.
  63 The latter allocates all additional data structures on the dump memory (faster)
  64 for which no explicit freeing is necessary after the processing. Care needs to
  65 be taken to not accidentally free parts of these structures by calling
  66 'dump_release' too early.
  67
  68 After usage, a list can be freed with
  69         chain_free.
  70 (use only if the list was created with 'chain_new')
  71
  72
  73 Adding elements is easy with:
  74         chain_addafter, chain_addlast, chain_addbefore, chain_addfirst
  75
  76 Search the list with:
  77         chain_first, chain_last, chain_prev, chain_next, chain_this
  78
  79 Delete elements from the list:
  80         chain_remove, chain_remove_go_prev, chain_removespecific
  81
  82
  83 ATTENTION: As mentioned earlier, there are no pointers to the list or to other
  84 nodes inside the list elements, so list elements cannot be used as pointers
  85 into the list. Therefore a 'cursor' is used to make one element current. Every
  86 insertion/deletion occurs at a position relative to this cursor.
  87
  88 */
  89
  90 #endif