1 /* @include ajlist ************************************************************
2 **
3 ** AJAX List functions
4 ** These functions create and control linked lists.
5 **
6 ** @author Copyright (C) 1998 Ian Longden
7 ** @version $Revision: 1.48 $
8 ** @modified 2001 Alan Bleasby
9 **              Changed lists to be double-linked, completely rewrote
10 **              iterator handling and added back-iteration functions.
11 **              Operation of ajListInsert made more intuitive.
12 ** @modified $Date: 2012/07/02 15:47:30 $ by $Author: rice $
13 ** @@
14 **
15 ** This library is free software; you can redistribute it and/or
16 ** modify it under the terms of the GNU Lesser General Public
17 ** License as published by the Free Software Foundation; either
18 ** version 2.1 of the License, or (at your option) any later version.
19 **
20 ** This library is distributed in the hope that it will be useful,
21 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
22 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
23 ** Lesser General Public License for more details.
24 **
25 ** You should have received a copy of the GNU Lesser General Public
26 ** License along with this library; if not, write to the Free Software
27 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
28 ** MA  02110-1301,  USA.
29 **
30 ******************************************************************************/
31 
32 #ifndef AJLIST_H
33 #define AJLIST_H
34 
35 /* ========================================================================= */
36 /* ============================= include files ============================= */
37 /* ========================================================================= */
38 
39 #include "ajdefine.h"
40 #include "ajstr.h"
41 
42 AJ_BEGIN_DECLS
43 
44 
45 
46 
47 /* ========================================================================= */
48 /* =============================== constants =============================== */
49 /* ========================================================================= */
50 
51 
52 
53 
54 /* @enum AjEListType **********************************************************
55 **
56 ** AJAX List Type enumeration
57 **
58 ** @value ajEListTypeAny Any data
59 ** @value ajEListTypeStr String data
60 ** @@
61 ******************************************************************************/
62 
63 typedef enum AjOListType
64 {
65     ajEListTypeAny,
66     ajEListTypeStr
67 } AjEListType;
68 
69 
70 
71 
72 /* ========================================================================= */
73 /* ============================== public data ============================== */
74 /* ========================================================================= */
75 
76 
77 
78 
79 /* @data AjPListNode **********************************************************
80 **
81 ** AJAX List Node
82 **
83 ** @alias AjSListNode
84 ** @alias AjOListNode
85 **
86 ** @attr Next [struct AjSListNode*] Next AJAX List Node object
87 ** @attr Prev [struct AjSListNode*] Previous AJAX List Node object
88 ** @attr Item [void*] Data value
89 ** @@
90 ******************************************************************************/
91 
92 typedef struct AjSListNode
93 {
94     struct AjSListNode* Next;
95     struct AjSListNode* Prev;
96     void* Item;
97 } AjOListNode;
98 
99 #define AjPListNode AjOListNode*
100 
101 
102 
103 
104 /* @data AjPList **************************************************************
105 **
106 ** List data object. Lists are simple linked lists with performance optimised
107 ** to allow rapid extension of the beginning or end of the list.
108 **
109 ** Lists can hold any data type. Special functions are available for lists
110 ** of AjPStr values. In general, these functions are the same. Many are
111 ** provided for ease of use to save remembering which calls need special cases.
112 **
113 ** @alias AjSList
114 ** @alias AjOList
115 **
116 ** @attr First [AjPListNode] first node
117 ** @attr Last [AjPListNode] dummy last node
118 ** @attr Fitemdel [void function] Item destructor, or NULL if not an object
119 ** @attr Count [ajulong] Number of nodes
120 ** @attr Use [ajuint] Reference count
121 ** @attr Padding [AjBool] Padding to alignment boundary
122 ** @@
123 ******************************************************************************/
124 
125 typedef struct AjSList
126 {
127     AjPListNode First;
128     AjPListNode Last;
129     void (*Fitemdel)(void** Pitem);
130     ajulong Count;
131     ajuint Use;
132     AjBool Padding;
133 } AjOList;
134 
135 #define AjPList AjOList*
136 
137 
138 
139 
140 /* @data AjIList **************************************************************
141 **
142 ** AJAX list iterator data structure
143 **
144 ** @alias AjSIList
145 ** @alias AjOIList
146 **
147 ** @attr Head [AjPList] Head of modifiable list
148 ** @attr ReadHead [const AjPList] Head of read-only list
149 ** @attr Here [AjPListNode] Current list node
150 ** @attr Back [AjBool] Direction of last iterative move, true if reading back
151 ** @attr Modify [AjBool] Allows iterator to modify the sequence
152 **
153 ** @@
154 ******************************************************************************/
155 
156 typedef struct AjSIList
157 {
158     AjPList Head;
159     const AjPList ReadHead;
160     AjPListNode Here;
161     AjBool Back;
162     AjBool Modify;
163 } AjOIList;
164 
165 #define AjIList AjOIList*
166 
167 
168 
169 
170 /*
171 ** Prototype definitions
172 */
173 
174 AjPList     ajListNewRef(AjPList list);
175 AjPList     ajListNewListref(const AjPList list);
176 void        ajListExit(void);
177 AjBool      ajListPeekFirst(const AjPList thys, void** Pitem);
178 void        ajListFree(AjPList* Plist);
179 void        ajListFreeData(AjPList* Plist);
180 AjIList     ajListIterNew(AjPList list);
181 AjIList     ajListIterNewBack(AjPList list);
182 AjIList     ajListIterNewreadBack(const AjPList list);
183 AjIList     ajListIterNewread(const AjPList list);
184 AjBool      ajListIterDoneBack(const AjIList iter);
185 void        ajListIterDel(AjIList* iter);
186 void*       ajListIterGet(AjIList iter);
187 void*       ajListIterGetBack(AjIList iter);
188 void        ajListIterRewind(AjIList iter);
189 AjBool      ajListIterDone(const AjIList iter);
190 void        ajListIterTrace(const AjIList iter);
191 void*       ajListDrop(AjPList thys, void* item);
192 AjBool      ajListPeekLast(const AjPList thys, void** Pitem);
193 AjBool      ajListPeekNumber(const AjPList thys, ajulong n, void** Pitem);
194 ajulong     ajListGetLength(const AjPList list);
195 ajulong     ajListstrGetMemsize(const AjPList list);
196 void        ajListMap(AjPList list,
197                       void (*apply)(void** Pitem, void* cl), void* cl);
198 void        ajListMapread(const AjPList list,
199                           void (*apply)(void* item, void* cl), void* cl);
200 AjPList     ajListNew(void);
201 AjBool      ajListPeek(const AjPList list, void** Pitem);
202 AjBool      ajListPop(AjPList list, void** Pitem);
203 AjBool      ajListPopLast(AjPList thys, void** Pitem);
204 void        ajListProbe(AjPList const* list);
205 void        ajListProbeData(AjPList const* list);
206 void        ajListPurge(AjPList list,
207                         AjBool (*test)(const void* item),
208                         void (*itemdel)(void** Pitem));
209 void        ajListPush(AjPList list, void* item);
210 void        ajListPushAppend(AjPList list, void* item);
211 void        ajListReverse(AjPList list);
212 
213 AjPList     ajListstrNewList(const AjPList list);
214 AjPList     ajListstrNewListref(const AjPList list);
215 void        ajListstrFree(AjPList* Plist);
216 void        ajListstrFreeData(AjPList* Plist);
217 AjPStr      ajListstrIterGet(AjIList iter);
218 AjPStr      ajListstrIterGetBack(AjIList iter);
219 void        ajListstrIterTrace(const AjIList iter);
220 ajulong     ajListstrGetLength(const AjPList list);
221 void        ajListstrMap(AjPList thys,
222                          void (*apply)(AjPStr* str, void* cl), void* cl);
223 void        ajListstrMapread(const AjPList thys,
224                              void (*apply)(AjPStr str, void* cl), void* cl);
225 AjPList     ajListstrNew(void);
226 AjBool      ajListstrPeek(const AjPList list, AjPStr* Pstr);
227 AjBool      ajListstrPop(AjPList list, AjPStr* Pstr);
228 AjBool      ajListstrPopLast(AjPList thys, AjPStr* Pstr);
229 void        ajListstrPush(AjPList list, AjPStr str);
230 void        ajListstrPushAppend(AjPList list, AjPStr str);
231 void        ajListstrReverse(AjPList list);
232 ajulong     ajListstrToarray(const AjPList list, AjPStr** array);
233 ajulong     ajListstrToarrayAppend(const AjPList list, AjPStr** array);
234 void        ajListstrTrace(const AjPList list);
235 
236 ajulong     ajListToarray(const AjPList list, void*** array);
237 ajulong     ajListToindex(const AjPList list, ajuint* listindex,
238                           int (*compar1)(const void* item1,
239                                          const void* item2));
240 void        ajListTrace(const AjPList list);
241 
242 AjBool      ajListMapfind(const AjPList listhead,
243                           AjBool (*apply)(void** Pitem, void* cl),
244                           void* cl);
245 AjBool      ajListstrMapfind(const AjPList listhead,
246                              AjBool (*apply)(AjPStr* Pstr, void* cl),
247                              void* cl);
248 
249 void        ajListPushlist(AjPList list, AjPList* Plist);
250 void        ajListstrPushlist(AjPList list, AjPList* Plist);
251 void        ajListIterInsert(AjIList iter, void* item);
252 void        ajListIterRemove(AjIList iter);
253 void        ajListstrIterInsert(AjIList iter, AjPStr str);
254 void        ajListstrIterRemove(AjIList iter);
255 void        ajListSort(AjPList thys,
256                        int (*compar1)(const void* item1,
257                                       const void* item2));
258 void        ajListSortTwo(AjPList thys,
259                           int (*compar1)(const void* item1,
260                                          const void* item2),
261                           int (*compar2)(const void* item1,
262                                          const void* item2));
263 void        ajListSortTwoThree(AjPList thys,
264                                int (*compar1)(const void* item1,
265                                               const void* item2),
266                                int (*compar2)(const void* item1,
267                                               const void* item2),
268                                int (*compar3)(const void* item1,
269                                               const void* item2));
270 
271 void        ajListSortUnique(AjPList thys,
272                              int (*compar1)(const void* item1,
273                                             const void* item2),
274                              void (*itemdel)(void** Pitem,
275                                              void* cl));
276 void        ajListSortTwoUnique(AjPList thys,
277                                 int (*compar1)(const void* item1,
278                                                const void* item2),
279                                 int (*compar2)(const void* item1,
280                                                const void* item2),
281                                 void (*itemdel)(void** Pitem,
282                                                 void* cl));
283 void        ajListUnused(void** array);
284 
285 /*
286 ** End of prototype definitions
287 */
288 
289 
290 
291 
292 #ifdef AJ_COMPILE_DEPRECATED_BOOK
293 #endif /* AJ_COMPILE_DEPRECATED_BOOK */
294 
295 #ifdef AJ_COMPILE_DEPRECATED
296 
297 __deprecated void        ajListPushList(AjPList list, AjPList* Plist);
298 __deprecated void        ajListstrPushList(AjPList list, AjPList* Plist);
299 __deprecated ajuint      ajListstrClone(const AjPList thys, AjPList newlist);
300 __deprecated AjPList     ajListNewArgs(void* x, ...);
301 
302 __deprecated AjPListNode ajListNodesNew(void *x, ...);
303 __deprecated AjPList  ajListstrNewArgs(AjPStr x, ...);
304 
305 __deprecated AjPList  ajListCopy(const AjPList list);
306 __deprecated void     ajListPushApp(AjPList list, void* item);
307 
308 __deprecated void     ajListAppend(AjPList list, AjPListNode* tail);
309 __deprecated ajuint   ajListLength(const AjPList list);
310 
311 __deprecated AjBool   ajListFirst(const AjPList thys, void** Pitem);
312 __deprecated AjBool   ajListLast(const AjPList thys, void** Pitem);
313 __deprecated AjBool   ajListNth(const AjPList thys, ajuint n, void** Pitem);
314 __deprecated AjBool   ajListPopEnd(AjPList thys, void** Pitem);
315 __deprecated void     ajListstrPushApp(AjPList list, AjPStr str);
316 __deprecated void     ajListDel(AjPList* Plist);
317 __deprecated AjBool   ajListstrPopEnd(AjPList thys, AjPStr* Pstr);
318 __deprecated ajuint   ajListstrToArray(const AjPList list, AjPStr** array);
319 __deprecated ajuint   ajListstrToArrayApp(const AjPList list, AjPStr** array);
320 __deprecated ajuint   ajListToArray(const AjPList list, void*** array);
321 __deprecated ajuint   ajListstrLength(const AjPList list);
322 __deprecated AjBool   ajListFind(const AjPList listhead,
323                                  AjBool (*apply)(void** Pitem, void* cl),
324                                  void* cl);
325 __deprecated AjBool   ajListstrFind(const AjPList listhead,
326                                     AjBool (*apply)(AjPStr* Pstr, void* cl),
327                                     void* cl);
328 
329 __deprecated void     ajListMapRead(const AjPList list,
330                                     void apply(void* item, void* cl),
331                                     void* cl);
332 __deprecated void     ajListstrMapRead(const AjPList thys,
333                                        void (*apply)(AjPStr str, void* cl),
334                                        void* cl);
335 
336 __deprecated void     ajListstrDel(AjPList* Plist);
337 __deprecated AjPList  ajListstrCopy(const AjPList list);
338 
339 __deprecated AjIList  ajListIter(AjPList list);
340 __deprecated AjIList  ajListIterBack(AjPList list);
341 __deprecated AjIList  ajListIterBackRead(const AjPList list);
342 __deprecated AjIList  ajListIterRead(const AjPList list);
343 __deprecated AjBool   ajListIterBackDone(const AjIList iter);
344 __deprecated AjBool   ajListIterBackMore(const AjIList iter);
345 __deprecated void*    ajListIterBackNext(AjIList iter);
346 __deprecated void     ajListIterFree(AjIList* iter);
347 __deprecated AjBool   ajListIterMoreBack(const AjIList iter);
348 __deprecated AjBool   ajListIterMore(const AjIList iter);
349 __deprecated void*    ajListIterNext(AjIList iter);
350 
351 __deprecated void     ajListInsert(AjIList iter, void* item);
352 __deprecated void     ajListRemove(AjIList iter);
353 
354 __deprecated void     ajListstrInsert(AjIList iter, AjPStr str);
355 __deprecated void     ajListstrRemove(AjIList iter);
356 __deprecated void     ajListSort2(AjPList thys,
357                                   int (*compar1)(const void* item1,
358                                                  const void* item2),
359                                   int (*compar2)(const void* item1,
360                                                  const void* item2));
361 __deprecated void     ajListSort3(AjPList thys,
362                                   int (*compar1)(const void* item1,
363                                                  const void* item2),
364                                   int (*compar2)(const void* item1,
365                                                  const void* item2),
366                                   int (*compar3)(const void* item1,
367                                                  const void* item2));
368 
369 __deprecated void     ajListUnique(AjPList thys,
370                                    int (*compar)(const void* item1,
371                                                  const void* item2),
372                                    void (*itemdel)(void** Pitem,
373                                                    void* cl));
374 __deprecated void     ajListUnique2(AjPList thys,
375                                     int (*compar1)(const void* item1,
376                                                    const void* item2),
377                                     int (*compar2)(const void* item1,
378                                                    const void* item2),
379                                     void (*itemdel)(void** Pitem,
380                                                     void* cl));
381 
382 __deprecated void     ajListGarbageCollect(AjPList list,
383                                            void (*itemdel)(void** Pitem),
384                                            AjBool (*test)(const void* item));
385 
386 #endif /* AJ_COMPILE_DEPRECATED */
387 
388 
389 
390 
391 AJ_END_DECLS
392 
393 #endif /* !AJLIST_H */
394