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