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