pd.if.org Git - lice/blob - list.h

   1 #ifndef LICE_UTIL_LIST_HDR
   2 #define LICE_UTIL_LIST_HDR
   3 #include <stdbool.h>
   4
   5 /*
   6  * Macro: SENTINEL_LIST
   7  *  Initialize an empty list in place
   8  */
   9 #define SENTINEL_LIST ((list_t) { \
  10         .length    = 0,           \
  11         .head      = NULL,        \
  12         .tail      = NULL         \
  13 })
  14
  15 /*
  16  * Type: list_iterator_t
  17  *  A type capable of representing an itrator for a <list>
  18  */
  19 typedef struct list_iterator_s list_iterator_t;
  20
  21 /*
  22  * Type: list_t
  23  *  A standard double-linked list
  24  */
  25 typedef struct list_s list_t;
  26
  27 /*
  28  * Function: list_create
  29  *  Creates a new list
  30  */
  31 list_t *list_create(void);
  32
  33 /*
  34  * Function: list_push
  35  *  Push an element onto a list
  36  */
  37 void list_push(list_t *list, void *element);
  38
  39 /*
  40  * Function: list_pop
  41  *  Pop an element from a list
  42  */
  43 void *list_pop(list_t *list);
  44
  45 /*
  46  * Function: list_length
  47  *  Used to retrieve length of a list object
  48  */
  49 int list_length(list_t *list);
  50
  51 /*
  52  * Function: list_shift
  53  *  Like a list_pop but shift from the head (instead of the tail)
  54  */
  55 void *list_shift(list_t *list);
  56
  57 /*
  58  * Function: list_reverse
  59  *  Reverse the contents of a list
  60  */
  61 list_t *list_reverse(list_t *list);
  62
  63 /*
  64  * Function: list_iterator
  65  *  Create an iterator for a given list object
  66  */
  67 list_iterator_t *list_iterator(list_t *list);
  68
  69 /*
  70  * Function: list_iterator_next
  71  *  Increment the list iterator while returning the given element
  72  */
  73 void *list_iterator_next(list_iterator_t *iter);
  74
  75 /*
  76  * Function: list_iterator_end
  77  *  Test if the iterator is at the end of the list
  78  */
  79 bool list_iterator_end(list_iterator_t *iter);
  80
  81 /*
  82  * Function: list_tail
  83  *  Get the last element in a list
  84  *
  85  * Parameters:
  86  *  list - The list in question to get the last element of.
  87  *
  88  * Returns:
  89  *  The last element in the list.
  90  */
  91 void *list_tail(list_t *list);
  92
  93 /*
  94  * Function: list_head
  95  *  Get the first element in a list
  96  *
  97  * Parameters:
  98  *  list - The list in question to get the first element of.
  99  *
 100  * Returns:
 101  *  The first element in the list.
 102  */
 103 void *list_head(list_t *list);
 104
 105 /*
 106  * Function: list_empty
 107  *  Empty the contents of a list
 108  *
 109  * Parameters:
 110  *  list - The list to empty the contents of.
 111  */
 112 void list_empty(list_t *list);
 113
 114 /*
 115  * Function: list_default
 116  *  Create a new list default initializing the first element with
 117  *  an item.
 118  *
 119  * Parameters:
 120  *  item - The first item to default initialize the list with.
 121  *
 122  * Returns:
 123  *  A new list containing one element holding `item`.
 124  */
 125 list_t *list_default(void *item);
 126
 127 struct list_s {
 128     int                 length;
 129     struct list_node_s *head;
 130     struct list_node_s *tail;
 131 };
 132
 133 #endif