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