1 /* 2 $Id: ll.h,v 1.1 2005/05/29 08:24:04 airborne Exp $ 3 4 Copyright (C) 2005 Kris Verbeeck <airborne@advalvas.be> 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License as published by the Free Software Foundation; either 9 version 2 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public 17 License along with this library; if not, write to the 18 Free Software Foundation, Inc., 59 Temple Place - Suite 330, 19 Boston, MA 02111-1307, USA. 20 */ 21 22 #ifndef LL_H 23 #define LL_H 1 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 30 /* --- type definitions */ 31 32 33 /** 34 * Linked list element. 35 */ 36 typedef struct elem_s elem_t; 37 38 /** 39 * Linked list. 40 */ 41 typedef struct list_s list_t; 42 43 /** 44 * Callback prototype for destroying element data. 45 */ 46 typedef void elem_destroy_cb(void *data); 47 48 49 /* --- construction / destruction */ 50 51 52 /** 53 * Creates a new linked list. 54 * 55 * @param cb The callback used to destroy the element data or NULL if 56 * no further action is required. 57 * @return The linked list structure or NULL if memory allocation failed. 58 */ 59 list_t *list_new(elem_destroy_cb *cb); 60 61 /** 62 * Free all resources associated with the given linked list. Embedded 63 * data will be freed by use of the callback registered at list 64 * creation. 65 * 66 * @param list The linked list. 67 */ 68 void list_destroy(list_t *list); 69 70 /** 71 * Remove all elements from the list without destroying the list 72 * itself. Embedded data will be freed by use of the callback 73 * registered at list creation. 74 * 75 * @param list The linked list. 76 */ 77 void list_flush(list_t *list); 78 79 80 /* --- list elements --- */ 81 82 /** 83 * Retrieves the data associated with a list element. 84 * 85 * @param elem The list element. 86 * @return The data associated with the element or NULL if the element 87 * was invalid. 88 */ 89 void *element_data(elem_t *elem); 90 91 92 /* --- getters & setters --- */ 93 94 95 /** 96 * Append a new element to the end of the list. 97 * 98 * @param list The linked list. 99 * @param data The data to append to the list. 100 * @return The list element that was appended or NULL if memory 101 * allocation fails or the list is invalid. 102 */ 103 elem_t *list_append(list_t *list, void *data); 104 105 /** 106 * Returns the number of elements in the list. 107 * 108 * @param list The linked list. 109 * @return The number of elements. 110 */ 111 int list_size(list_t *list); 112 113 /** 114 * Returns the list element at the specified index or NULL if the 115 * index is invalid. 116 * 117 * @param list The linked list. 118 * @param idx The element index (first = 0). 119 * @return The element or NULL if not found. 120 */ 121 elem_t *list_get(list_t *list, int idx); 122 123 /** 124 * Returns the first list element. 125 * 126 * @param list The linked list. 127 * @return The first element or NULL if the list is empty. 128 */ 129 elem_t *list_first(list_t *list); 130 131 /** 132 * Returns the next list element. Before using this function you 133 * should call list_first to initialize the iterator. 134 * 135 * @param list The linked list. 136 * @return The next element or NULL if not found. 137 */ 138 elem_t *list_next(list_t *list); 139 140 141 /* --- iteration */ 142 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #endif /* LL_H */ 149