1 /* @include ajtable *********************************************************** 2 ** 3 ** AJAX table functions 4 ** 5 ** Hash table functions. 6 ** 7 ** @author Copyright (C) 1998 Ian Longden 8 ** @version $Revision: 1.40 $ 9 ** @modified 2011 pmr Auto-resizing, destructors, table merges 10 ** @modified $Date: 2013/02/17 13:39:55 $ by $Author: mks $ 11 ** @@ 12 ** 13 ** This library is free software; you can redistribute it and/or 14 ** modify it under the terms of the GNU Lesser General Public 15 ** License as published by the Free Software Foundation; either 16 ** version 2.1 of the License, or (at your option) any later version. 17 ** 18 ** This library is distributed in the hope that it will be useful, 19 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 20 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 ** Lesser General Public License for more details. 22 ** 23 ** You should have received a copy of the GNU Lesser General Public 24 ** License along with this library; if not, write to the Free Software 25 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 26 ** MA 02110-1301, USA. 27 ** 28 ******************************************************************************/ 29 30 #ifndef AJTABLE_H 31 #define AJTABLE_H 32 33 /* ========================================================================= */ 34 /* ============================= include files ============================= */ 35 /* ========================================================================= */ 36 37 #include "ajdefine.h" 38 #include "ajstr.h" 39 40 AJ_BEGIN_DECLS 41 42 43 44 45 /* ========================================================================= */ 46 /* =============================== constants =============================== */ 47 /* ========================================================================= */ 48 49 50 51 52 /* @enum AjETableType ********************************************************* 53 ** 54 ** AJAX Table Type enumeration 55 ** 56 ** @value ajETableTypeUnknown no type set 57 ** @value ajETableTypeChar char* type 58 ** @value ajETableTypeStr AJAX String (AjPStr) type 59 ** @value ajETableTypeInt AJAX integer (ajint) type 60 ** @value ajETableTypeUint AJAX unsigned integer (ajuint) type 61 ** @value ajETableTypeLong AJAX long integer (ajlong) type 62 ** @value ajETableTypeUlong AJAX unsigned long integer (ajulong) type 63 ** @value ajETableTypeUser user-defined type 64 ** @value ajETableTypeMax beyond last defined value 65 ** 66 ******************************************************************************/ 67 68 typedef enum AjOTableType 69 { 70 ajETableTypeUnknown, 71 ajETableTypeChar, 72 ajETableTypeStr, 73 ajETableTypeInt, 74 ajETableTypeUint, 75 ajETableTypeLong, 76 ajETableTypeUlong, 77 ajETableTypeUser, 78 ajETableTypeMax 79 } AjETableType; 80 81 82 83 84 /* ========================================================================= */ 85 /* ============================== public data ============================== */ 86 /* ========================================================================= */ 87 88 89 90 91 /* @data AjPTableNode ********************************************************* 92 ** 93 ** AJAX Table Node object. 94 ** 95 ** @attr Link [struct AjSTableNode*] Link top next AJAX Table Node 96 ** @attr Key [void*] Key data 97 ** @attr Value [void*] Value data 98 ** @@ 99 ******************************************************************************/ 100 101 typedef struct AjSTableNode { 102 struct AjSTableNode* Link; 103 void* Key; 104 void* Value; 105 } AjOTableNode; 106 107 #define AjPTableNode AjOTableNode* 108 109 110 111 112 /* @data AjPTable ************************************************************* 113 ** 114 ** Hash table object. Tables are key/value pairs with a simple hash function 115 ** to provide rapid searching for keys. 116 ** 117 ** Tables can hold any data type. Special functions are available for 118 ** tables of AjPStr values, but these are in the ajstr library, 119 ** and start with ajStrTable... 120 ** 121 ** In general, these functions are the same 122 ** but with different hash and comparison functions used. Alternative 123 ** function names are provided in all cases to save remembering which 124 ** calls need special cases. 125 ** 126 ** @new ajTableNew Creates a table. 127 ** @delete ajTableFree Deallocates and clears a table. 128 ** @modify ajTablePut Adds or updates a value for a given key. 129 ** @modify ajTableMap Calls a function for each key/value in a table. 130 ** @modify ajTableRemove Removes a key/value pair from a table, and returns 131 ** the value. 132 ** @cast ajTableToarray Creates an array to hold each key value pair 133 ** in pairs of array elements. The last element is null. 134 ** @cast ajTableGet Returns the value for a given key. 135 ** @cast ajTableLength Returns the number of keys in a table. 136 ** @output ajTableTrace Writes debug messages to trace the contents of a table. 137 ** 138 ** @attr Fcmp [ajint function] Key compare function 139 ** (0 for match, -1 or +1 if not matched) 140 ** @attr Fhash [ajulong function] Hash function 141 ** @attr Fkeydel [void function] Key destructor, or NULL if not an object 142 ** @attr Fvaldel [void function] Value destructor, or NULL if not an object 143 ** @attr Buckets [AjPTableNode*] Buckets of AJAX Table Node objects 144 ** @attr Size [ajulong] Size - number of hash buckets 145 ** @attr Length [ajulong] Number of entries 146 ** @attr Timestamp [ajuint] Time stamp 147 ** @attr Use [ajuint] Reference count 148 ** @attr Padding [ajuint] Padding to alignment boundary 149 ** @attr Type [AjETableType] AJAX Table Type enumeration 150 ** @@ 151 ******************************************************************************/ 152 153 typedef struct AjSTable 154 { 155 ajint (*Fcmp)(const void* key1, const void* key2); 156 ajulong (*Fhash)(const void* key, ajulong hashsize); 157 void (*Fkeydel)(void** Pkey); 158 void (*Fvaldel)(void** Pvalue); 159 AjPTableNode* Buckets; 160 ajulong Size; 161 ajulong Length; 162 ajuint Timestamp; 163 ajuint Use; 164 ajuint Padding; 165 AjETableType Type; 166 } AjOTable; 167 168 #define AjPTable AjOTable* 169 170 171 172 173 /* ========================================================================= */ 174 /* =========================== public functions ============================ */ 175 /* ========================================================================= */ 176 177 178 179 180 /* 181 ** Prototype definitions 182 */ 183 184 void ajTableExit(void); 185 void ajTableClear(AjPTable table); 186 void ajTableClearDelete(AjPTable table); 187 void ajTableDel(AjPTable* table); 188 void ajTableDelKeydelValdel(AjPTable* table, 189 void (*keydel)(void** Pvalue), 190 void (*valdel)(void** Pvalue)); 191 void ajTableDelValdel(AjPTable* table, 192 void (*valdel)(void** Pvalue)); 193 void ajTableFree(AjPTable* table); 194 195 const void* ajTableFetchV(const AjPTable table, const void* key); 196 void* ajTableFetchmodV(const AjPTable table, const void* key); 197 void* ajTableFetchmodTraceV(const AjPTable table, const void* key); 198 199 const ajint* ajTableintFetch(const AjPTable table, const ajint* intkey); 200 ajint* ajTableintFetchmod(AjPTable table, const ajint* key); 201 202 const ajlong* ajTablelongFetch(const AjPTable table, const ajlong* longkey); 203 ajlong* ajTablelongFetchmod(AjPTable table, const ajlong* key); 204 205 const ajuint* ajTableuintFetch(const AjPTable table, const ajuint* uintkey); 206 ajuint* ajTableuintFetchmod(AjPTable table, const ajuint* key); 207 208 const ajulong* ajTableulongFetch(const AjPTable table, 209 const ajulong* ulongkey); 210 ajulong* ajTableulongFetchmod(AjPTable table, const ajulong* key); 211 212 const void* ajTableFetchC(const AjPTable table, const char* txtkey); 213 const void* ajTableFetchS(const AjPTable table, const AjPStr key); 214 void* ajTableFetchmodC(const AjPTable table, const char* txtkey); 215 void* ajTableFetchmodS(const AjPTable table, const AjPStr key); 216 217 ajulong ajTableGetLength(const AjPTable table); 218 ajulong ajTableGetSize(const AjPTable table); 219 void ajTableMap(AjPTable table, 220 void (*apply)(const void* key, 221 void** Pvalue, 222 void* cl), 223 void* cl); 224 void ajTableMapDel(AjPTable table, 225 void (*apply)(void** Pkey, 226 void** Pvalue, 227 void* cl), 228 void* cl); 229 AjBool ajTableMergeAnd(AjPTable thys, AjPTable table); 230 AjBool ajTableMergeEor(AjPTable thys, AjPTable table); 231 AjBool ajTableMergeNot(AjPTable thys, AjPTable table); 232 AjBool ajTableMergeOr(AjPTable thys, AjPTable table); 233 void* ajTablePut(AjPTable table, void* key, void* value); 234 AjBool ajTablePutClean(AjPTable table, void* key, void* value, 235 void (*keydel)(void** Pkey), 236 void (*valdel)(void** Pvalue)); 237 void* ajTablePutTrace(AjPTable table, void* key, 238 void* value); 239 240 void* ajTableRemove(AjPTable table, const void* key); 241 void* ajTableRemoveKey(AjPTable table, const void* key, 242 void** truekey); 243 void ajTableResizeCount(AjPTable table, ajulong size); 244 245 void ajTableResizeHashsize(AjPTable table, ajulong hashsize); 246 247 ajulong ajTableToarrayKeys(const AjPTable table, 248 void*** keyarray); 249 ajulong ajTableToarrayKeysValues(const AjPTable table, 250 void*** keyarray, void*** valarray); 251 ajulong ajTableToarrayValues(const AjPTable table, 252 void*** valarray); 253 254 255 AjPTable ajTablecharNew(ajulong hint); 256 AjPTable ajTablecharNewCase(ajulong hint); 257 AjPTable ajTablecharNewConst(ajulong hint); 258 AjPTable ajTablecharNewCaseConst(ajulong hint); 259 260 void ajTableTrace(const AjPTable table); 261 void ajTablecharPrint(const AjPTable table); 262 void ajTablestrPrint(const AjPTable table); 263 void ajTablestrTrace(const AjPTable table); 264 void ajTablestrTracekeys(const AjPTable table); 265 266 ajint ajTablecharCmp(const void* key1, const void* key2); 267 ajint ajTablecharCmpCase(const void* key1, const void* key2); 268 ajint ajTableintCmp(const void* key1, const void* key2); 269 ajint ajTableuintCmp(const void* key1, const void* key2); 270 ajint ajTablelongCmp(const void* key1, const void* key2); 271 ajint ajTableulongCmp(const void* key1, const void* key2); 272 ajint ajTablestrCmp(const void* key1, const void* key2); 273 ajint ajTablestrCmpCase(const void* key1, const void* key2); 274 275 ajulong ajTablecharHash(const void* key, ajulong hashsize); 276 ajulong ajTablecharHashCase(const void* key, ajulong hashsize); 277 ajulong ajTableintHash(const void* key, ajulong hashsize); 278 ajulong ajTablelongHash(const void* key, ajulong hashsize); 279 ajulong ajTableuintHash(const void* key, ajulong hashsize); 280 ajulong ajTableulongHash(const void* key, ajulong hashsize); 281 ajulong ajTablestrHash(const void* key, ajulong hashsize); 282 ajulong ajTablestrHashCase(const void* key, ajulong hashsize); 283 284 AjPTable ajTableintNew(ajulong size); 285 AjPTable ajTableintNewConst(ajulong size); 286 AjPTable ajTablelongNew(ajulong size); 287 AjPTable ajTablelongNewConst(ajulong size); 288 AjPTable ajTableuintNew(ajulong size); 289 AjPTable ajTableuintNewConst(ajulong size); 290 AjPTable ajTableulongNew(ajulong size); 291 AjPTable ajTableulongNewConst(ajulong size); 292 void ajTableintFree(AjPTable* ptable); 293 void ajTableintFreeKey(AjPTable* ptable); 294 void ajTablelongFree(AjPTable* ptable); 295 void ajTablelongFreeKey(AjPTable* ptable); 296 void ajTableuintFree(AjPTable* ptable); 297 void ajTableuintFreeKey(AjPTable* ptable); 298 void ajTableulongFree(AjPTable* ptable); 299 void ajTableulongFreeKey(AjPTable* ptable); 300 AjPTable ajTablestrNew(ajulong size); 301 AjPTable ajTablestrNewCase(ajulong size); 302 AjPTable ajTablestrNewConst(ajulong size); 303 AjPTable ajTablestrNewCaseConst(ajulong size); 304 305 void ajTablestrFree(AjPTable* ptable); 306 void ajTablestrFreeKey(AjPTable* ptable); 307 308 AjPTable ajTableNew(ajulong size); 309 AjPTable ajTableNewFunctionLen(ajulong size, 310 ajint (*cmp)(const void* key1, 311 const void* key2), 312 ajulong (*hash)(const void* key, 313 ajulong hashsize), 314 void (*keydel)(void** Pkey), 315 void (*valdel)(void** Pvalue)); 316 const AjPStr ajTablestrFetchkeyC(const AjPTable table, const char* key); 317 const AjPStr ajTablestrFetchkeyS(const AjPTable table, const AjPStr key); 318 319 void ajTableSetDestroy(AjPTable table, 320 void (*keydel)(void** Pkey), 321 void (*valdel)(void** Pvalue)); 322 void ajTableSetDestroyboth(AjPTable table); 323 void ajTableSetDestroykey(AjPTable table, 324 void (*keydel)(void** Pkey)); 325 void ajTableSetDestroyvalue(AjPTable table, 326 void (*valdel)(void** Pvalue)); 327 328 void ajTableSettypeDefault(AjPTable table); 329 void ajTableSettypeChar(AjPTable table); 330 void ajTableSettypeCharCase(AjPTable table); 331 void ajTableSettypeInt(AjPTable table); 332 void ajTableSettypeLong(AjPTable table); 333 void ajTableSettypeUint(AjPTable table); 334 void ajTableSettypeUlong(AjPTable table); 335 void ajTableSettypeString(AjPTable table); 336 void ajTableSettypeStringCase(AjPTable table); 337 void ajTableSettypeUser(AjPTable table, 338 ajint (*cmp)(const void* key1, 339 const void* key2), 340 ajulong (*hash)(const void* key, 341 ajulong hashsize)); 342 343 AjBool ajTableMatchC(const AjPTable table, const char* key); 344 AjBool ajTableMatchS(const AjPTable table, const AjPStr key); 345 AjBool ajTableMatchV(const AjPTable table, const void* key); 346 347 void* ajTablestrFetchC(const AjPTable table, const char* txtkey); 348 void* ajTablestrFetchS(const AjPTable table, const AjPStr key); 349 AjPStr* ajTablestrFetchmod(AjPTable table, const AjPStr key); 350 351 /* 352 ** End of prototype definitions 353 */ 354 355 356 357 358 #ifdef AJ_COMPILE_DEPRECATED_BOOK 359 #endif /* AJ_COMPILE_DEPRECATED_BOOK */ 360 361 #ifdef AJ_COMPILE_DEPRECATED 362 363 __deprecated AjPTable ajTableNewLen(ajuint size); 364 __deprecated AjPTable ajTablestrNewCaseLen(ajuint size); 365 __deprecated AjPTable ajTablestrNewLen(ajuint size); 366 __deprecated void* ajTableFetch(const AjPTable table, const void* key); 367 __deprecated const void* ajTableFetchKey(const AjPTable table, 368 const void* key); 369 __deprecated AjPTable ajTablecharNewCaseLen(ajuint hint); 370 __deprecated const AjPStr ajTablestrFetch(const AjPTable table, 371 const AjPStr key); 372 __deprecated ajuint ajTableToarray(const AjPTable table, 373 void*** keyarray, void*** valarray); 374 __deprecated ajint ajTableLength(const AjPTable table); 375 __deprecated void* ajTableGet(const AjPTable table, const void* key); 376 __deprecated ajint ajStrTableCmp(const void* key1, const void* key2); 377 __deprecated ajint ajStrTableCmpC(const void* key1, const void* key2); 378 __deprecated ajint ajStrTableCmpCase(const void* key1, const void* key2); 379 __deprecated ajint ajStrTableCmpCaseC(const void* key1, const void* key2); 380 __deprecated ajuint ajStrTableHash(const void* key, ajuint hashsize); 381 __deprecated ajuint ajStrTableHashC(const void* key, ajuint hashsize); 382 __deprecated ajuint ajStrTableHashCase(const void* key, ajuint hashsize); 383 __deprecated ajuint ajStrTableHashCaseC(const void* key, ajuint hashsize); 384 __deprecated AjPTable ajStrTableNewC(ajuint hint); 385 __deprecated AjPTable ajStrTableNewCase(ajuint hint); 386 __deprecated AjPTable ajStrTableNewCaseC(ajuint hint); 387 __deprecated void ajStrTablePrint(const AjPTable table); 388 __deprecated void ajStrTablePrintC(const AjPTable table); 389 __deprecated void ajStrTableTrace(const AjPTable table); 390 391 __deprecated AjPTable ajTableNewL(ajuint size, 392 ajint (*cmp)(const void* key1, 393 const void* key2), 394 ajuint (*hash)(const void* key, 395 ajuint hashsize)); 396 __deprecated const void* ajTableKey(const AjPTable table, const void* key); 397 __deprecated void ajStrTableFree(AjPTable* table); 398 __deprecated AjPTable ajStrTableNew(ajuint hint); 399 __deprecated void ajStrTableFreeKey(AjPTable* table); 400 401 #endif /* AJ_COMPILE_DEPRECATED */ 402 403 404 405 406 AJ_END_DECLS 407 408 #endif /* !AJTABLE_H */ 409