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