list.h

   1 /*
   2         List
   3         ----
   4
   5         A linked list.
   6 */
   7
   8 #ifndef _DRAGONSTD_LIST_H_ // include guard
   9 #define _DRAGONSTD_LIST_H_
  10
  11 #include "bits/callback.h" // for Iterator, Comparator
  12
  13 #define LIST_ITERATE(list, node) for (ListNode *node = (list)->fst; node != NULL; node = node->nxt)
  14
  15 typedef struct ListNode {
  16         /* public */
  17         void *dat;            // pointer to data
  18         /* private */
  19         struct ListNode *nxt; // next node
  20 } ListNode;
  21
  22 typedef struct {
  23         /* private */
  24         ListNode *fst;  // first element
  25         ListNode **end; // where address of next node will be stored
  26 } List;
  27
  28 void list_ini(List *list);
  29 /*
  30         Initializes the list.
  31
  32         The list should be uninitialized or empty before passed to this function.
  33         This function should be called before any other function is called on the list.
  34 */
  35
  36 void *list_add(List *list, void *dat, Comparator cmp, Transformer trans);
  37 /*
  38         Add an element to the list.
  39
  40         If an equal element is already on the list, return it and don't add anything.
  41         Otherwise, return added element.
  42 */
  43
  44 void *list_get(List *list, void *key, Comparator cmp, Transformer trans);
  45 /*
  46         Get an element from the list.
  47
  48         The first matching element is returned, or NULL if none found.
  49 */
  50
  51 void *list_del(List *list, void *key, Comparator cmp, Transformer trans);
  52 /*
  53         Delete an element from the list.
  54
  55         The first matching element is returned (after being removed from the list), or NULL
  56                 if none found.
  57 */
  58
  59 void list_apd(List *list, void *dat);
  60 /*
  61         Append an element at the end of the list.
  62 */
  63
  64 void list_ppd(List *list, void *dat);
  65 /*
  66         Prepend an element at the start of the list.
  67 */
  68
  69 ListNode **list_nfd(List *list, void *key, Comparator cmp);
  70 /*
  71         Find the location of the first node matching key.
  72
  73         This can be either an existing node, or the location the next new node would need to
  74                 be stored.
  75 */
  76
  77 void list_nmk(List *list, ListNode **node, void *dat);
  78 /*
  79         Create a node with dat as data and store it's pointer at the given location.
  80 */
  81
  82 void list_nrm(List *list, ListNode **node);
  83 /*
  84         Remove the node at the given location.
  85 */
  86
  87 void list_itr(List *list, Iterator iter, void *arg, Transformer trans);
  88 /*
  89         Iterate over the list.
  90         Calls iter on every element, with the extra argument arg.
  91
  92         Note: the LIST_ITERATE macro can be used to do this without function calls.
  93 */
  94
  95 void list_clr(List *list, Iterator iter, void *arg, Transformer trans);
  96 /*
  97         Iterates over the list and deletes all elements.
  98         Calls iter on every element, with the extra argument arg.
  99
 100         The list is empty afterwards.
 101 */
 102
 103 #endif // _DRAGONSTD_LIST_H_