1 #pragma once 2 3 #include <stdbool.h> 4 #include <stdlib.h> 5 6 struct list_node_t; 7 typedef struct list_node_t list_node_t; 8 9 struct list_t; 10 typedef struct list_t list_t; 11 12 typedef void (*list_free_cb)(void *data); 13 14 // Iterator callback prototype used for |list_foreach|. 15 // |data| represents the list item currently being iterated, |context| is a 16 // user defined value passed into |list_foreach|. 17 // Callback must return true to continue iterating or false to stop iterating. 18 typedef bool (*list_iter_cb)(void *data, void *context); 19 20 // Returns a new, empty list. Returns NULL if not enough memory could be allocated 21 // for the list structure. The returned list must be freed with |list_free|. The 22 // |callback| specifies a function to be called whenever a list element is removed 23 // from the list. It can be used to release resources held by the list element, e.g. 24 // memory or file descriptor. |callback| may be NULL if no cleanup is necessary on 25 // element removal. 26 list_t *list_new(list_free_cb callback); 27 28 // Frees the list. This function accepts NULL as an argument, in which case it 29 // behaves like a no-op. 30 void list_free(list_t *list); 31 32 // Returns true if |list| is empty (has no elements), false otherwise. 33 // |list| may not be NULL. 34 bool list_is_empty(const list_t *list); 35 36 // Returns true if the list contains |data|, false otherwise. 37 // |list| may not be NULL. 38 bool list_contains(const list_t *list, const void *data); 39 40 // Returns the length of the |list|. |list| may not be NULL. 41 size_t list_length(const list_t *list); 42 43 // Returns the first element in the list without removing it. |list| may not 44 // be NULL or empty. 45 void *list_front(const list_t *list); 46 47 // Returns the last element in the list without removing it. |list| may not 48 // be NULL or empty. 49 void *list_back(const list_t *list); 50 51 // Returns the last node in the list without removing it. |list| may not 52 // be NULL or empty. 53 list_node_t *list_back_node(const list_t *list); 54 55 // Inserts |data| after |prev_node| in |list|. |data|, |list|, and |prev_node| 56 // may not be NULL. This function does not make a copy of |data| so the pointer 57 // must remain valid at least until the element is removed from the list or the 58 // list is freed. Returns true if |data| could be inserted, false otherwise 59 // (e.g. out of memory). 60 bool list_insert_after(list_t *list, list_node_t *prev_node, void *data); 61 62 // Inserts |data| at the beginning of |list|. Neither |data| nor |list| may be NULL. 63 // This function does not make a copy of |data| so the pointer must remain valid 64 // at least until the element is removed from the list or the list is freed. 65 // Returns true if |data| could be inserted, false otherwise (e.g. out of memory). 66 bool list_prepend(list_t *list, void *data); 67 68 // Inserts |data| at the end of |list|. Neither |data| nor |list| may be NULL. 69 // This function does not make a copy of |data| so the pointer must remain valid 70 // at least until the element is removed from the list or the list is freed. 71 // Returns true if |data| could be inserted, false otherwise (e.g. out of memory). 72 bool list_append(list_t *list, void *data); 73 74 // Removes |data| from the list. Neither |list| nor |data| may be NULL. If |data| 75 // is inserted multiple times in the list, this function will only remove the first 76 // instance. If a free function was specified in |list_new|, it will be called back 77 // with |data|. This function returns true if |data| was found in the list and removed, 78 // false otherwise. 79 bool list_remove(list_t *list, void *data); 80 81 // Removes all elements in the list. Calling this function will return the list to the 82 // same state it was in after |list_new|. |list| may not be NULL. 83 void list_clear(list_t *list); 84 85 // Iterates through the |list| and calls |callback| for each data element. Iteration 86 // continues until |callback| returns false. The function returns the pointer to last 87 // processed element, or NULL if the list is empty, or all calls to |callback| returned 88 // true. |context| is passed to |callback| on each iteration. 89 // If the list is empty, |callback| will never be called. It is safe to mutate the 90 // list inside the callback. If an element is added before the node being visited, 91 // there will be no callback for the newly-inserted node. Neither |list| nor 92 // |callback| may be NULL. 93 list_node_t *list_foreach(const list_t *list, list_iter_cb callback, void *context); 94 95 // Returns an iterator to the first element in |list|. |list| may not be NULL. 96 // The returned iterator is valid as long as it does not equal the value returned 97 // by |list_end|. 98 list_node_t *list_begin(const list_t *list); 99 100 // Returns an iterator that points past the end of the list. In other words, 101 // this function returns the value of an invalid iterator for the given list. 102 // When an iterator has the same value as what's returned by this function, you 103 // may no longer call |list_next| with the iterator. |list| may not be NULL. 104 list_node_t *list_end(const list_t *list); 105 106 // Given a valid iterator |node|, this function returns the next value for the 107 // iterator. If the returned value equals the value returned by |list_end|, the 108 // iterator has reached the end of the list and may no longer be used for any 109 // purpose. 110 list_node_t *list_next(const list_node_t *node); 111 112 // Returns the value stored at the location pointed to by the iterator |node|. 113 // |node| must not equal the value returned by |list_end|. 114 void *list_node(const list_node_t *node); 115