1/*************************************************************************** 2 $RCSfile$ 3 ------------------- 4 cvs : $Id$ 5 begin : Sat Jun 28 2003 6 copyright : (C) 2003 by Martin Preuss 7 email : martin@libchipcard.de 8 9 *************************************************************************** 10 * * 11 * This library is free software; you can redistribute it and/or * 12 * modify it under the terms of the GNU Lesser General Public * 13 * License as published by the Free Software Foundation; either * 14 * version 2.1 of the License, or (at your option) any later version. * 15 * * 16 * This library is distributed in the hope that it will be useful, * 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 19 * Lesser General Public License for more details. * 20 * * 21 * You should have received a copy of the GNU Lesser General Public * 22 * License along with this library; if not, write to the Free Software * 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * 24 * MA 02111-1307 USA * 25 * * 26 ***************************************************************************/ 27 28 29#ifndef @TYPENAME@_LIST2_H 30#define @TYPENAME@_LIST2_H 31 32 33#ifdef __cplusplus 34extern "C" { 35#endif 36 37 /** 38 * Defines a list of pointers to @TYPENAME@. The pointers stored in 39 * a list are not taken over by the list, so you must take care of freeing 40 * the elements of the list yourself. 41 * (see @ref @FN_PREFIX@_List2_new) 42 */ 43 typedef struct @TYPENAME@_LIST2 @TYPENAME@_LIST2; 44 45 /** 46 * An iterator is used to traverse a list. 47 */ 48 typedef struct @TYPENAME@_LIST2_ITERATOR @TYPENAME@_LIST2_ITERATOR; 49 50 /** 51 * See @ref @FN_PREFIX@_List2_ForEach. 52 */ 53 typedef @TYPENAME@* (@TYPENAME@_LIST2_FOREACH)(@TYPENAME@ *element, 54 void *user_data); 55 56 /** 57 * Creates a new list. This mus be freed using @ref @FN_PREFIX@_List2_free. 58 */ 59 @TYPENAME@_LIST2 *@FN_PREFIX@_List2_new(); 60 61 /** 62 * Destroys the list. Please note that the members in this list are not destroyed! 63 */ 64 void @FN_PREFIX@_List2_free(@TYPENAME@_LIST2 *l); 65 66 /** 67 * Dumps the contents of the list to an open file (e.g. stderr). 68 */ 69 void @FN_PREFIX@_List2_Dump(@TYPENAME@_LIST2 *l, FILE *f, unsigned int indent); 70 71 /** 72 * Appends an element to a list making it the new last element. 73 */ 74 void @FN_PREFIX@_List2_PushBack(@TYPENAME@_LIST2 *l, @TYPENAME@ *p); 75 76 /** 77 * Inserts an element at the start of the list, making it the new 78 * first element. 79 */ 80 void @FN_PREFIX@_List2_PushFront(@TYPENAME@_LIST2 *l, @TYPENAME@ *p); 81 82 /** 83 * Returns the first element of the list. (The element is not 84 * removed from the list.) 85 */ 86 @TYPENAME@ *@FN_PREFIX@_List2_GetFront(@TYPENAME@_LIST2 *l); 87 88 /** 89 * Returns the last element of the list. (The element is not 90 * removed from the list.) 91 */ 92 @TYPENAME@ *@FN_PREFIX@_List2_GetBack(@TYPENAME@_LIST2 *l); 93 94 /** 95 * Removes the element currently pointed to by the given iterator 96 * from the list. 97 */ 98 void @FN_PREFIX@_List2_Erase(@TYPENAME@_LIST2 *l, 99 @TYPENAME@_LIST2_ITERATOR *it); 100 101 /** Returns the size of this list, i.e. the number of elements in this 102 * list. 103 * 104 * This number is counted in the list metadata, so this is a cheap 105 * operation. */ 106 unsigned int @FN_PREFIX@_List2_GetSize(@TYPENAME@_LIST2 *l); 107 108 /** 109 * Removes the list's last element from the list. (The element is not 110 * freed.) 111 */ 112 void @FN_PREFIX@_List2_PopBack(@TYPENAME@_LIST2 *l); 113 114 /** 115 * Removes the list's first element from the list. (The element is not 116 * freed.) 117 */ 118 void @FN_PREFIX@_List2_PopFront(@TYPENAME@_LIST2 *l); 119 120 /** 121 * Removes all list elements from the list. (The elements are not freed.) 122 */ 123 void @FN_PREFIX@_List2_Clear(@TYPENAME@_LIST2 *l); 124 125 /** 126 * Returns a list iterator pointing to the first element. 127 */ 128 @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2_First(@TYPENAME@_LIST2 *l); 129 130 /** 131 * Returns a list iterator pointing to the last element. 132 */ 133 @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2_Last(@TYPENAME@_LIST2 *l); 134 135 /** 136 * Creates a list iterator for the given list. (FIXME: Should be private). 137 */ 138 @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2Iterator_new(@TYPENAME@_LIST2 *l); 139 140 /** 141 * Destroys the list iterator. 142 */ 143 void @FN_PREFIX@_List2Iterator_free(@TYPENAME@_LIST2_ITERATOR *li); 144 145 /** 146 * Moves the list iterator to the predecessor of the currenty selected 147 * element and returns that predecessor element. 148 */ 149 @TYPENAME@ *@FN_PREFIX@_List2Iterator_Previous(@TYPENAME@_LIST2_ITERATOR *li); 150 151 /** 152 * Moves the list iterator to the successor of the currenty selected 153 * element and returns that successor element. 154 */ 155 @TYPENAME@ *@FN_PREFIX@_List2Iterator_Next(@TYPENAME@_LIST2_ITERATOR *li); 156 157 /** 158 * Returns the pointer to the element stored at the list position the 159 * iterator currently points to. 160 */ 161 @TYPENAME@ *@FN_PREFIX@_List2Iterator_Data(@TYPENAME@_LIST2_ITERATOR *li); 162 163 /** Traverses the list, calling the callback function 'func' on 164 * each list element. Traversal will stop when 'func' returns a 165 * non-NULL value, and the routine will return with that 166 * value. Otherwise the routine will return NULL. 167 * @param list The list to traverse. 168 * @param func The function to be called with each list element. 169 * @param user_data A pointer passed on to the function 'func'. 170 * @return The non-NULL pointer returned by 'func' as soon as it 171 * returns one. Otherwise (i.e. 'func' always returns NULL) 172 * returns NULL. 173 */ 174 @TYPENAME@ *@FN_PREFIX@_List2_ForEach(@TYPENAME@_LIST2 *list, 175 @TYPENAME@_LIST2_FOREACH func, 176 void *user_data); 177 178 179 typedef struct @TYPENAME@_CONSTLIST2 @TYPENAME@_CONSTLIST2; 180 typedef struct @TYPENAME@_CONSTLIST2_ITERATOR @TYPENAME@_CONSTLIST2_ITERATOR; 181 typedef const @TYPENAME@* 182 (@TYPENAME@_CONSTLIST2_FOREACH)(const @TYPENAME@ *element, 183 void *user_data); 184 185 186 @TYPENAME@_CONSTLIST2 *@FN_PREFIX@_ConstList2_new(); 187 188 void @FN_PREFIX@_ConstList2_free(@TYPENAME@_CONSTLIST2 *l); 189 190 void @FN_PREFIX@_ConstList2_PushBack(@TYPENAME@_CONSTLIST2 *l, const @TYPENAME@ *p); 191 192 void @FN_PREFIX@_ConstList2_PushFront(@TYPENAME@_CONSTLIST2 *l, const @TYPENAME@ *p); 193 194 const @TYPENAME@ *@FN_PREFIX@_ConstList2_GetFront(@TYPENAME@_CONSTLIST2 *l); 195 196 const @TYPENAME@ *@FN_PREFIX@_ConstList2_GetBack(@TYPENAME@_CONSTLIST2 *l); 197 198 unsigned int @FN_PREFIX@_ConstList2_GetSize(@TYPENAME@_CONSTLIST2 *l); 199 200 void @FN_PREFIX@_ConstList2_PopBack(@TYPENAME@_CONSTLIST2 *l); 201 202 void @FN_PREFIX@_ConstList2_PopFront(@TYPENAME@_CONSTLIST2 *l); 203 204 void @FN_PREFIX@_ConstList2_Clear(@TYPENAME@_CONSTLIST2 *l); 205 206 @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2_First(@TYPENAME@_CONSTLIST2 *l); 207 208 @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2_Last(@TYPENAME@_CONSTLIST2 *l); 209 210 @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2Iterator_new(@TYPENAME@_CONSTLIST2 *l); 211 212 void @FN_PREFIX@_ConstList2Iterator_free(@TYPENAME@_CONSTLIST2_ITERATOR *li); 213 214 const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Previous(@TYPENAME@_CONSTLIST2_ITERATOR *li); 215 216 const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Next(@TYPENAME@_CONSTLIST2_ITERATOR *li); 217 218 const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Data(@TYPENAME@_CONSTLIST2_ITERATOR *li); 219 220 /** Traverses the list, calling the callback function 'func' on 221 * each list element. Traversal will stop when 'func' returns a 222 * non-NULL value, and the routine will return with that 223 * value. Otherwise the routine will return NULL. 224 * @param list The list to traverse. 225 * @param func The function to be called with each list element. 226 * @param user_data A pointer passed on to the function 'func'. 227 * @return The non-NULL pointer returned by 'func' as soon as it 228 * returns one. Otherwise (i.e. 'func' always returns NULL) 229 * returns NULL. 230 */ 231 const @TYPENAME@ *@FN_PREFIX@_ConstList2_ForEach(@TYPENAME@_CONSTLIST2 *list, 232 @TYPENAME@_CONSTLIST2_FOREACH func, void *user_data); 233 234 235#ifdef __cplusplus 236} 237#endif 238 239 240#endif /* @TYPENAME@_LIST_H */ 241 242 243 244