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