1: /*
2: * Copyright (C) 2007-2018 Tobias Brunner
3: * Copyright (C) 2005-2008 Martin Willi
4: * Copyright (C) 2005 Jan Hutter
5: * HSR Hochschule fuer Technik Rapperswil
6: *
7: * This program is free software; you can redistribute it and/or modify it
8: * under the terms of the GNU General Public License as published by the
9: * Free Software Foundation; either version 2 of the License, or (at your
10: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11: *
12: * This program is distributed in the hope that it will be useful, but
13: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15: * for more details.
16: */
17:
18: /**
19: * @defgroup linked_list linked_list
20: * @{ @ingroup collections
21: */
22:
23: #ifndef LINKED_LIST_H_
24: #define LINKED_LIST_H_
25:
26: typedef struct linked_list_t linked_list_t;
27:
28: #include <collections/enumerator.h>
29:
30: /**
31: * Function to match elements in a linked list
32: *
33: * @param item current list item
34: * @param args user supplied data
35: * @return TRUE, if the item matched, FALSE otherwise
36: */
37: typedef bool (*linked_list_match_t)(void *item, va_list args);
38:
39: /**
40: * Helper function to match a string in a linked list of strings
41: *
42: * @param item list item (char*)
43: * @param args user supplied data (char*)
44: * @return
45: */
46: bool linked_list_match_str(void *item, va_list args);
47:
48: /**
49: * Function to be invoked on elements in a linked list
50: *
51: * @param item current list item
52: * @param args user supplied data
53: */
54: typedef void (*linked_list_invoke_t)(void *item, va_list args);
55:
56: /**
57: * Class implementing a double linked list.
58: *
59: * General purpose linked list. This list is not synchronized.
60: */
61: struct linked_list_t {
62:
63: /**
64: * Gets the count of items in the list.
65: *
66: * @return number of items in list
67: */
68: int (*get_count) (linked_list_t *this);
69:
70: /**
71: * Create an enumerator over the list.
72: *
73: * @note The enumerator's position is invalid before the first call
74: * to enumerate().
75: *
76: * @return enumerator over list items
77: */
78: enumerator_t* (*create_enumerator)(linked_list_t *this);
79:
80: /**
81: * Resets the enumerator's current position to the beginning of the list.
82: *
83: * @param enumerator enumerator to reset
84: */
85: void (*reset_enumerator)(linked_list_t *this, enumerator_t *enumerator);
86:
87: /**
88: * Inserts a new item at the beginning of the list.
89: *
90: * @param item item value to insert in list
91: */
92: void (*insert_first) (linked_list_t *this, void *item);
93:
94: /**
95: * Removes the first item in the list and returns its value.
96: *
97: * @param item returned value of first item, or NULL
98: * @return SUCCESS, or NOT_FOUND if list is empty
99: */
100: status_t (*remove_first) (linked_list_t *this, void **item);
101:
102: /**
103: * Inserts a new item before the item the enumerator currently points to.
104: *
105: * If this method is called after all items have been enumerated, the item
106: * is inserted last. This is helpful when inserting items into a sorted
107: * list.
108: *
109: * @note The position of the enumerator is not changed. So it is safe to
110: * call this before or after remove_at() to replace the item at the current
111: * position (the enumerator will continue with the next item in the list).
112: * And in particular, when inserting an item before calling enumerate(),
113: * the enumeration will continue (or start) at the item that was first in
114: * the list before any items were inserted (enumerate() will return FALSE
115: * if the list was empty before).
116: *
117: * @param enumerator enumerator with position
118: * @param item item value to insert in list
119: */
120: void (*insert_before)(linked_list_t *this, enumerator_t *enumerator,
121: void *item);
122:
123: /**
124: * Remove an item from the list where the enumerator points to.
125: *
126: * If this method is called before calling enumerate() of the enumerator,
127: * the first item in the list, if any, will be removed. No item is removed,
128: * if the method is called after enumerating all items.
129: *
130: * @param enumerator enumerator with position
131: */
132: void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
133:
134: /**
135: * Remove items from the list matching the given item.
136: *
137: * If a compare function is given, it is called for each item, with the
138: * first parameter being the current list item and the second parameter
139: * being the supplied item. Return TRUE from the compare function to remove
140: * the item, return FALSE to keep it in the list.
141: *
142: * If compare is NULL, comparison is done by pointers.
143: *
144: * @param item item to remove/pass to comparator
145: * @param compare compare function, or NULL
146: * @return number of removed items
147: */
148: int (*remove)(linked_list_t *this, void *item, bool (*compare)(void*,void*));
149:
150: /**
151: * Returns the value of the first list item without removing it.
152: *
153: * @param item returned value of first item
154: * @return SUCCESS, NOT_FOUND if list is empty
155: */
156: status_t (*get_first) (linked_list_t *this, void **item);
157:
158: /**
159: * Inserts a new item at the end of the list.
160: *
161: * @param item value to insert into list
162: */
163: void (*insert_last) (linked_list_t *this, void *item);
164:
165: /**
166: * Removes the last item in the list and returns its value.
167: *
168: * @param item returned value of last item, or NULL
169: * @return SUCCESS, NOT_FOUND if list is empty
170: */
171: status_t (*remove_last) (linked_list_t *this, void **item);
172:
173: /**
174: * Returns the value of the last list item without removing it.
175: *
176: * @param item returned value of last item
177: * @return SUCCESS, NOT_FOUND if list is empty
178: */
179: status_t (*get_last) (linked_list_t *this, void **item);
180:
181: /**
182: * Find the first matching element in the list.
183: *
184: * The first object passed to the match function is the current list item,
185: * followed by the user supplied data.
186: * If the supplied function returns TRUE so does this function, and the
187: * current object is returned in the third parameter (if given), otherwise,
188: * the next item is checked.
189: *
190: * If match is NULL, *item and the current object are compared.
191: *
192: * @param match comparison function to call on each object, or NULL
193: * @param item the list item, if found, or NULL
194: * @param ... user data to supply to match function
195: * @return TRUE if found, FALSE otherwise (or if neither match,
196: * nor item is supplied)
197: */
198: bool (*find_first)(linked_list_t *this, linked_list_match_t match,
199: void **item, ...);
200:
201: /**
202: * Invoke a method on all of the contained objects.
203: *
204: * If a linked list contains objects with function pointers,
205: * invoke() can call a method on each of the objects. The
206: * method is specified by an offset of the function pointer,
207: * which can be evaluated at compile time using the offsetof
208: * macro, e.g.: list->invoke(list, offsetof(object_t, method));
209: *
210: * @param offset offset of the method to invoke on objects
211: */
212: void (*invoke_offset)(linked_list_t *this, size_t offset);
213:
214: /**
215: * Invoke a function on all of the contained objects.
216: *
217: * @param function function to call for each object
218: * @param ... user data to supply to called function
219: */
220: void (*invoke_function)(linked_list_t *this, linked_list_invoke_t function,
221: ...);
222:
223: /**
224: * Clones a list and its objects using the objects' clone method.
225: *
226: * @param offset offset to the objects clone function
227: * @return cloned list
228: */
229: linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
230:
231: /**
232: * Compare two lists and their objects for equality using the given equals
233: * method.
234: *
235: * @param other list to compare
236: * @param offset offset of the objects equals method
237: * @return TRUE if lists and objects are equal, FALSE otherwise
238: */
239: bool (*equals_offset) (linked_list_t *this, linked_list_t *other,
240: size_t offset);
241:
242: /**
243: * Compare two lists and their objects for equality using the given function.
244: *
245: * @param other list to compare
246: * @param function function to compare the objects
247: * @return TRUE if lists and objects are equal, FALSE otherwise
248: */
249: bool (*equals_function) (linked_list_t *this, linked_list_t *other,
250: bool (*)(void*,void*));
251:
252: /**
253: * Destroys a linked_list object.
254: */
255: void (*destroy) (linked_list_t *this);
256:
257: /**
258: * Destroys a list and its objects using the destructor.
259: *
260: * If a linked list and the contained objects should be destroyed, use
261: * destroy_offset. The supplied offset specifies the destructor to
262: * call on each object. The offset may be calculated using the offsetof
263: * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
264: *
265: * @param offset offset of the objects destructor
266: */
267: void (*destroy_offset) (linked_list_t *this, size_t offset);
268:
269: /**
270: * Destroys a list and its contents using a a cleanup function.
271: *
272: * If a linked list and its contents should get destroyed using a specific
273: * cleanup function, use destroy_function. This is useful when the
274: * list contains malloc()-ed blocks which should get freed,
275: * e.g.: list->destroy_function(list, free);
276: *
277: * @param function function to call on each object
278: */
279: void (*destroy_function) (linked_list_t *this, void (*)(void*));
280: };
281:
282: /**
283: * Creates an empty linked list object.
284: *
285: * @return linked_list_t object.
286: */
287: linked_list_t *linked_list_create(void);
288:
289: /**
290: * Creates a linked list from an enumerator.
291: *
292: * @param enumerator enumerator over void*, gets destroyed
293: * @return linked_list_t object, containing enumerated values
294: */
295: linked_list_t *linked_list_create_from_enumerator(enumerator_t *enumerator);
296:
297: /**
298: * Creates a linked list from a NULL terminated vararg list of items.
299: *
300: * @param first first item
301: * @param ... subsequent items, terminated by NULL
302: * @return linked_list_t object, containing passed items
303: */
304: linked_list_t *linked_list_create_with_items(void *first, ...);
305:
306: #endif /** LINKED_LIST_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to linked_list.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / collections